Skip to main content

API Quickstart

Get from zero to a first outbound call in a few minutes.

1) Create an API key​

In the dashboard, create an API key under:

/client/api-keys

The key is shown once, so copy it somewhere safe. You will send it in the Authorization header.

2) Prepare an assistant​

In the dashboard, pick the assistant you want to call with and check that it is published and has an outbound phone number linked. Copy its ID from the assistant's page.

An assistant that is missing either of those returns 422 INVALID_CONFIG when you try to call with it.

3) Trigger an outbound call​

curl --request POST "https://api.yourcalls.ai/public/v1/calls" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "assistant_id": "12345678-1234-4234-9234-1234567890ab",
    "target_phone_number": "+442079460958",
    "variables": {
      "first_name": "Alex"
    },
    "metadata": {
      "crm_record": "12345"
    }
  }'

Each key you send in variables becomes a variable the assistant reads as {{vars.<name>}}, so first_name above is {{vars.first_name}}. Use lower case with underscores, because a camelCase key is not a valid variable name. See Variables.

Expected response:

{
  "success": true,
  "data": {
    "request_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "call_id": "ffffffff-1111-4222-8333-444444444444",
    "status": "in_progress",
    "from_number": "+447700900999"
  },
  "error": null,
  "requestId": "req-abc123",
  "apiVersion": 1
}

Store data.request_id. It is how you identify this specific call later, including with support. The envelope's own requestId is a different value that identifies the HTTP request rather than the call.

status is in_progress because the call has been accepted and dialling has started. It does not mean the call has been answered.

4) Review the outcome in the dashboard​

When the call finishes, its outcome, summary, transcript, and recording appear in Call History in the dashboard.

There is no endpoint for reading call results back. The API triggers calls; the dashboard is where you review them.

What to expect​

  • The request body is strict. An unrecognised field is a 400, not an ignored field.
  • Fields are snake_case in both the request body and the response data.
  • variables and metadata hold string values only.
  • On 429 CONCURRENCY_FULL or a 502, retry with backoff.
  • On a 402 or 403, stop retrying. The account needs credit, a plan change, or a billing fix first.

Next: Calls for the full field reference, and Errors for every response code.