Creating calls

POST /v1/calls places a call and returns as soon as it is queued. It does not wait for the call to be answered. Full schema and playground: Create an outbound call.

{
  "agent_id": "3f1c1b2e-...",
  "to_number": "+15555550100",
  "from_number": "+15555550199",
  "variables": {
    "patient_name": "Jane Doe",
    "appointment_date": "2026-09-15"
  },
  "metadata": {
    "your_order_id": "ORD-8812"
  }
}

string

required

The agent to place the call with. Find it in the dashboard under Agents: open the agent and copy the ID shown under its name. Only active, outbound agents can place calls; others are rejected with agent_inactive or agent_not_outbound.

string

required

Number to dial. E.164 (+1...) preferred.

string

Caller ID. If sent, it must equal the agent’s configured number or the request is rejected with from_number_mismatch.

object

Per-call values the agent’s script uses. Some are required per agent; a missing one is a 422 listing the keys.

object

Any JSON object. Stored untouched and echoed back on every webhook and on GET /v1/calls/{call_id}.

Retell-compatible aliases

A client written for Retell’s create-call endpoint works with only a URL change. override_agent_id maps to agent_id and retell_llm_dynamic_variables maps to variables. override_agent_version and any unknown fields are ignored.

{
  "override_agent_id": "3f1c1b2e-...",
  "override_agent_version": 2,
  "from_number": "+15555550199",
  "to_number": "+15555550100",
  "retell_llm_dynamic_variables": { "patient_name": "Jane Doe" },
  "metadata": { "your_order_id": "ORD-8812" }
}

Response

201
{
  "call_id": "9d2f7a3c-...",
  "status": "queued",
  "agent_id": "3f1c1b2e-...",
  "to_number": "+15555550100",
  "from_number": "+15555550199",
  "created_at": "2026-09-10T14:03:11.412Z"
}

call_id is stable for the life of the call. It is the same id on every webhook and on GET /v1/calls/{call_id}.

Errors

Errors come wrapped in a detail key. For validation and dispatch failures detail is an object with error, error_code, and where applicable extra fields. For auth and not-found errors it is a plain string.

422
{
  "detail": {
    "error": "Required variables are missing: patient_dob",
    "error_code": "missing_variables",
    "missing_variables": ["patient_dob"]
  }
}

Status	`error_code`	Meaning
401		Missing or invalid API key.
404	`agent_not_found`	No such agent in your organization.
400	`agent_not_outbound`, `agent_inactive`	The agent can’t place calls.
422	`missing_variables`	`missing_variables: [...]` lists what to add.
422	`from_number_mismatch`	`expected_from_number` tells you the right value.
422	`dnc_blocked`, `number_blocked`	The number is on a do-not-call or block list. A call record exists with `status: failed`.
502	`dispatch_error`, `dispatch_failed`	Transient failure placing the call. Safe to retry.

Reading a call

GET /v1/calls/{call_id} returns the call object as of now. GET /v1/calls/{call_id}/recording returns { "url": "...", "expires_at": "..." }, a fresh link to the recording valid for about an hour. It is 404 until a recording exists.

Get started

Calls

Webhooks

Retell-compatible aliases

Response

Errors

Reading a call

​Retell-compatible aliases

​Response

​Errors

​Reading a call

Retell-compatible aliases

Response

Errors

Reading a call