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 /v1/calls/{call_id}/transcript returns what was said, turn by turn. It is 404 until the call has ended (the call.ended webhook), and is never included on the call object or in webhook bodies. Only the agent’s and the caller’s speech is included; tool calls and other internal events are not.

curl https://api.contourvoice.com/v1/calls/9d2f7a3c-8e4b-4f1d-a6c7-2b3c4d5e6f70/transcript \
  -H "Authorization: Bearer sk_cont_..."

{
  "call_id": "9d2f7a3c-8e4b-4f1d-a6c7-2b3c4d5e6f70",
  "turns": [
    { "role": "user", "text": "Hello?", "interrupted": false,
      "started_at": "2026-09-10T14:03:19Z", "ended_at": "2026-09-10T14:03:20Z" },
    { "role": "agent", "text": "Hi, this is Ava calling from Contour with a critical radiology result. Am I speaking with Dr. Johnson?",
      "interrupted": false, "started_at": "2026-09-10T14:03:20Z", "ended_at": "2026-09-10T14:03:27Z" }
  ],
  "text": "Customer: Hello?\nAgent: Hi, this is Ava calling from Contour with a critical radiology result. Am I speaking with Dr. Johnson?"
}

turns is the conversation in order; role is agent or user. started_at and ended_at are present when timing was captured and absent otherwise. text is the same conversation as plain text, one Agent: / Customer: line per turn.

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