Making calls

Write access required.

Create a call — POST /v1/calls

Field	Type	Notes
agent_id	uuid, required	The AI agent that holds the conversation.
to	string, required	E.164 destination, e.g. +9198xxxxxxxx.
contact_id	uuid	Optional; must match to if given (422 contact_phone_mismatch). Otherwise the contact is found/created by number.
variables	object	Merged into the contact’s variables; available to the agent.
external_ref	string	Your identifier; echoed in webhooks; filterable.
idempotency_key	string	Dedupe key (or Idempotency-Key header; body wins).
scheduled_for	ISO 8601	Dial at/after this time. Default: now.
schedule_if_outside_hours	bool	Queue for the next calling window instead of rejecting. Default false.

Responses: 202 with the call request (status: "queued"); idempotent replay → 200 with the original. Pre-checks reject with 422 (invalid_agent, invalid_contact, contact_phone_mismatch, invalid_phone, recipient_dnd, consent_withdrawn, outside_calling_hours, validation_error), 402 insufficient_credits, 403 api_not_enabled. The same gates run again at dial time — a request that passed pre-checks can still end blocked if circumstances changed.

Call request object: id, status, call_id, to, agent_id, external_ref, scheduled_for, error_code, error_detail, dialed_at, completed_at, created_at, updated_at.

Track a request — GET /v1/call-requests/{id} · GET /v1/call-requests

List filters: status, external_ref (+ pagination). Real example of a dispatched request:

{
  "id": "9c033aed-3be9-4fa6-a9da-1f45f1f9aceb",
  "status": "completed",
  "call_id": "227e3804-e2e4-4d1b-8c25-050835e6ed31",
  "to": "+91XXXXX22338",
  "agent_id": "c071a030-8601-4e73-bfb2-872d49b42f38",
  "external_ref": "smoke-d1-86f292",
  "scheduled_for": "2026-06-05T12:54:18Z",
  "error_code": null, "error_detail": null,
  "dialed_at": "2026-06-05T12:54:24Z", "completed_at": "2026-06-05T12:54:24Z",
  "created_at": "2026-06-05T12:54:18Z", "updated_at": "2026-06-05T12:54:24Z"
}

Cancel — POST /v1/call-requests/{id}/cancel

Cancels a queued request → canceled. Anything past queued → 409 not_cancelable.