Place an outbound AI phone call

POST https://api.dairo.app/v1/phone/calls

Places an outbound AI voice call and returns immediately with the call in queued status; the dial runs asynchronously, so poll GET /v1/phone/calls/{id} or subscribe to call.status_changed to follow it to a terminal state. to and from are required E.164 numbers — from must be a number this account owns with status: "active", otherwise the request is a 400 — and instructions (required, up to 8,000 characters) tells the agent what to accomplish. {{name}} placeholders in instructions and greeting are filled from variables when the call is created (a placeholder with no matching variable stays as written). Every call runs on Dairo Live: model is optional and only dairo-live is accepted — any other value is a 400. Set voice to one of the 22 Dairo Live voice ids from the phone voice catalog (default marin; any other value is a 400) and language to the ISO code the agent speaks, like de; maxDurationSeconds caps the call between 30 and 780 seconds (default 600); and voicemailMessage (≤500 characters) is left on a voicemail — without it the agent hangs up silently when a mailbox answers. Pass up to 10 questions and the agent works them into the call, landing structured answers on the row afterward. Every connected call is recorded, and the agent hangs up by itself once the person says goodbye. Supply an Idempotency-Key header or idempotencyKey body field (≤128 characters) so a retried request returns the original call instead of dialing the person twice; a header that disagrees with the body field is a 400. The call emits a call.status_changed webhook to your subscribed endpoints when it is answered and when it reaches a terminal status. Price: $0.09 per minute for Dairo Live plus the destination's telephony rate, per started minute; a call that never connects is free. Requires the phone:call scope.

Scope: phone:call. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X POST "https://api.dairo.app/v1/phone/calls" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "string",
    "from": "string",
    "instructions": "string"
  }'

Headers

Body

Required, application/json: PhoneCallCreateRequest.

Calls are always recorded. To follow a call's progress subscribe a webhook to the call.status_changed event. The agent hangs up by itself when the person says goodbye.

Response

201 Created. Body: application/json, PhoneCall.

{
  "object": "phone_call",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "direction": "outbound",
  "status": "queued",
  "fromNumber": "string",
  "toNumber": "string",
  "instructions": null,
  "greeting": null,
  "voice": null,
  "model": null,
  "language": null,
  "maxDurationSeconds": null,
  "voicemailMessage": null,
  "queuedAt": "2026-10-19T09:30:00Z",
  "startedAt": "2026-10-19T09:30:00Z",
  "answeredAt": "2026-10-19T09:30:00Z",
  "endedAt": "2026-10-19T09:30:00Z",
  "durationSeconds": null,
  "hangupCause": null,
  "answeredBy": null,
  "summary": null,
  "notes": [
    {
      "kind": "task",
      "text": "Thanks for signing up.",
      "due": "string"
    }
  ],
  "costUsd": null,
  "error": null,
  "metadata": {},
  "idempotencyKey": null,
  "createdAt": "2026-10-19T09:30:00Z"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.