Skip to main content

Common Integration Patterns

Use these patterns to build reliable automations on top of the YourCalls API.

Pattern 1: Fire and forget​

POST /public/v1/calls triggers a call and returns as soon as the call is accepted. It does not wait for the call to finish, and there is no way to read the result back over the API.

  1. Call POST /public/v1/calls.
  2. Store data.request_id against whatever record in your system prompted the call.
  3. Return success to your app or workflow immediately.
  4. Review the outcome in Call History in the dashboard.

Programmatic retrieval of call outcomes is not currently available. If your workflow needs to branch on how a call went, do that work inside the call itself with a tool rather than by polling afterwards. A tool runs during or after the call and can post the result straight into your own system.

Why the trigger is worth treating as fire and forget:

  • Latency at trigger time stays low, because nothing waits on the call.
  • Your workflow never blocks on something that may take minutes.
  • Storing data.request_id still gives you a shared reference with support.

Pattern 2: Send your own identifiers through metadata​

Because you cannot look a call up later, the time to attach your identifiers is when you trigger it.

  • Put your record IDs in metadata. They are stored with the call and forwarded to your tools, so a tool can post results back to the right record in your system.
  • Values must be strings. Send numbers and dates as strings.
  • Avoid the reserved keys listed in Calls. Prefix your own, for example crm_contact_id rather than contact_id.

Pattern 3: Backoff on transient trigger failures​

When triggering calls at volume, treat these responses as retriable:

  • 429 CONCURRENCY_FULL
  • 502 PROVIDER_ERROR
  • 502 BEFORE_CALL_DISPATCH_FAILED
  • 500 INTERNAL_ERROR

Suggested retry schedule:

  • attempt 1: immediate
  • attempt 2: +1s
  • attempt 3: +2s
  • attempt 4: +4s

Do not retry a 402, a 403, a 404, or a 400. None of them clear on their own, and retrying only delays the fix. Surface these in your workflow as an actionable error instead. See Errors for which is which.

Pattern 4: Calling a contact you keep in YourCalls​

Every outbound call is attributed to a contact automatically. There is nothing to switch on and no flag to send.

  • The number you send as target_phone_number is matched to one of your contacts.
  • If no contact holds that number, one is usually created for it.
  • The call is then recorded against that contact, so it appears in their history in the dashboard and reaches your tools.

Attribution is best effort, and the call always takes priority over it. On the rare occasion a contact can be neither matched nor created, the call is still placed. It is recorded without a contact, so it does not appear in anybody's history and your tools receive no contact details for it.

If you want the contact to exist with real details rather than a bare phone number, create it first:

  1. POST /public/v1/contacts with the phone number and whatever else you hold, such as the name, the postcode, and your custom fields. See Contacts.
  2. POST /public/v1/calls with the same number in target_phone_number.

The call links to the contact you just wrote, because both are matched on the phone number. Sending the contact first is safe to repeat: it updates the existing contact rather than creating a second one.

You can name a matched contact's details directly in a prompt, a tool, or a workflow: {{contact.first_name}}, {{contact.postcode}} and the rest of the contact.* names read from the contact record, so you do not have to send them yourself. Use variables for values the contact record does not hold, such as an appointment time you have just booked. Each key you send there is read as {{vars.<name>}} and must be lower case with underscores. See Variables.