Calls

Accepts an outbound call and returns 201 with a callId. This is a paid operation. Charges come from your wallet.

Fields that aren't listed here are ignored.

Idempotency

Every request needs an Idempotency-Key header, so a retry after a timeout can't place a second call. Use one key per call you intend to make. A UUID or your own ID for the lead works well.

Bodies are compared by their content, so the order of JSON keys doesn't matter.

If the call was lost before it started, a repeat with the same key and body queues it again and returns 201. It still can't be dialed twice.

A replay returns what happened at the time, so status can be out of date. Read GET /v1/calls/{id} for the current state.

The body is validated before the key is looked at, so fixing an invalid body doesn't need a new key. When the request is refused with a 403, 404, 422 or 429, the key is released. Retry with the same key once you've cleared the cause.

A 503 IDEMPOTENCY_UNAVAILABLE means nothing was placed. Retry with the same key shortly.

A 503 SERVICE_UNAVAILABLE with Idempotency-Replay: true means the call couldn't be queued on the first attempt. That same key will keep returning this answer for 24 hours, so send a new key.

Phone number formats

phoneNumber is converted to E.164 before the call is queued. A number is accepted in these forms:

The result must be a valid number for its country. Anything else returns 400. Send the full international form for numbers outside the US and Canada.

Custom fields

customFields can have up to 50 keys, each up to 100 characters. It can be up to 16 KB in total, nested up to 32 levels deep.

Keys are converted to snake_case, so orderId becomes order_id. Common variants become one standard key, for example firstname and first both become first_name. Keys with empty or null values are dropped. A full_name value is built from the first and last name when you don't send one.

Keys that look like internal identifiers, such as user_id and file_id, are left out when contact_data is returned.

To narrow the recipient's calling hours, send an IANA time zone name such as America/Chicago. Use any of these keys: timezone, time_zone, timeZone, tz, customer_timezone or customerTimezone. See Calling hours.

First message

firstMessage can use placeholders in the form {{first_name}} or [first_name]. They are filled from the lead details in the request.

Calling hours

Calls only go out from 09:00 to 20:00 at the destination.

• A call requested outside those hours still returns 201. Its status stays queued until the hours open.
• A waiting call holds no funds and no line.
• A call that hasn't started 35 hours after you requested it fails with outside_calling_hours. It never goes out late.

The destination's hours come from the number being called. For US and Canadian numbers, that is the area code. Otherwise it is the country. When a number covers several time zones, the call waits until all of them are open. If those zones share less than 4 hours of the day, the country's main zone applies. If no time zone can be worked out, the call goes out without this check.

A time zone you send in customFields can only narrow these hours. It never widens them.

• A zone in the destination's country must be open as well as the number's own zones.
• A zone in another country is ignored, and so are UTC and Etc/UTC.
• A zone that would leave less than 4 shared hours is ignored.

Capacity

Two limits apply, and they work differently.

Queued and in-progress calls. Each account can have up to 100 calls queued or in progress through this route. Over that, the request returns 429 EXECUTION_CAPACITY_EXCEEDED with Retry-After: 60, and nothing is queued.

Concurrent lines. Each account has a limit on how many calls can be live at once. An accepted call that can't get a line stays queued and tries again every 30 seconds for up to 5 minutes. After that, it fails with line_capacity_reached, or with system_busy if the platform itself is at capacity. For a call that waited overnight, those 5 minutes start when the calling hours open.

Errors returned by this request

These 422 codes all include details.action, which says how to fix the problem.

Check isCallableForCampaigns on the phone number to catch most of these before you send a request.

Checks after the request succeeds

The checks above run again while the call waits, because things can change. Funds are checked only at this stage. A hold is placed on your wallet before dialing, covering the agent's maximum call duration, rounded up to whole minutes, at the per-minute price.

If one of these checks fails, the call's status becomes failed with a failure code. Read it with GET /v1/calls/{id}.

curl -X POST https://backend.synthesys.app/api/v1/calls \
  -H "SYNTH_API_KEY: YOUR_API_KEY" \
  -H "Idempotency-Key: lead-1042-renewal-call" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
    "phoneNumberId": "b2c4d6e8-1a3f-4c5d-8e7f-90a1b2c3d4e5",
    "phoneNumber": "+12025550123",
    "firstName": "Jane",
    "email": "jane@example.com",
    "customFields": { "timezone": "America/Chicago", "order_id": "A-1042" },
    "firstMessage": "Hi {{first_name}}, I am calling about order {{order_id}}.",
    "callContext": "outbound",
    "leadNotes": "Asked for a call back after 3pm."
  }'

{
  "success": true,
  "data": {
    "callId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "jobId": "0c9e7a52-4d1b-4f36-a8e2-7b6c5d4e3f21",
    "status": "queued"
  }
}

{
  "success": false,
  "error": "This phone number is assigned to a different agent.",
  "code": "PHONE_NUMBER_AGENT_MISMATCH",
  "requestId": "e3a1c5d7-2b4f-4a6c-9d8e-1f2a3b4c5d6e",
  "timestamp": "2026-10-31T14:02:11.482Z",
  "details": {
    "action": "Use the agent assigned to this number, or reassign the number first."
  }
}

{
  "success": false,
  "error": "This Idempotency-Key was already used with a different request. Send a new key to make a new request.",
  "code": "IDEMPOTENCY_KEY_REUSED",
  "requestId": "1d2c3b4a-5f6e-4d7c-8b9a-0f1e2d3c4b5a",
  "timestamp": "2026-10-31T14:03:40.120Z"
}

Returns one call object. Use the callId from POST /v1/calls. It works from the moment the call is accepted.

Errors

curl https://backend.synthesys.app/api/v1/calls/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "status": "completed",
    "failure_code": null,
    "failure_message": null,
    "agent_id": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
    "phone_number_id": "b2c4d6e8-1a3f-4c5d-8e7f-90a1b2c3d4e5",
    "provider_call_id": "2e4f6a8c-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
    "contact_phone": "+12025550123",
    "contact_data": {
      "first_name": "Jane",
      "full_name": "Jane",
      "email": "jane@example.com",
      "timezone": "America/Chicago",
      "order_id": "A-1042"
    },
    "lead_notes": "Asked for a call back after 3pm.",
    "duration_seconds": 184,
    "cost_usd": 1.84,
    "created_at": "2026-10-31T14:02:12.103Z",
    "completed_at": "2026-10-31T14:05:20.511Z"
  }
}

{
  "success": true,
  "data": {
    "id": "7c6d5e4f-3a2b-4c1d-8e0f-9a8b7c6d5e4f",
    "status": "failed",
    "failure_code": "insufficient_balance",
    "failure_message": "The wallet balance is too low to place this call.",
    "agent_id": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
    "phone_number_id": "b2c4d6e8-1a3f-4c5d-8e7f-90a1b2c3d4e5",
    "provider_call_id": null,
    "contact_phone": "+12025550123",
    "contact_data": { "first_name": "Jane", "full_name": "Jane" },
    "lead_notes": null,
    "duration_seconds": null,
    "cost_usd": null,
    "created_at": "2026-10-31T14:02:12.103Z",
    "completed_at": "2026-10-31T14:02:13.871Z"
  }
}