Skip to main content
POST
Place an outbound AI phone call

Authorizations

Authorization
string
header
required

Dairo API key, e.g. dairo_test_... or dairo_live_...

Headers

Idempotency-Key
string

Optional idempotency key for safe retries of side-effecting operations.

Maximum string length: 128

Body

application/json
to
string
required

Destination, E.164. A real phone rings here.

from
string
required

Caller id, E.164. MUST be a number this account owns with status active.

instructions
string
required

What the agent should accomplish. Supports {{handlebars}} filled from variables.

Maximum string length: 8000
greeting
string

Opening line spoken when the callee answers.

voice
string
default:Rime.Coda.lorelei
model
string
default:anthropic/claude-haiku-4-5
language
string
backgroundAudio
enum<string>
default:silence
Available options:
silence,
office,
none
maxDurationSeconds
integer
default:600

Hard cap on call length. The provider's own floor is 30 seconds.

Required range: 30 <= x <= 1800
record
boolean
default:true
variables
object

Values for {{handlebars}} placeholders.

webhookUrl
string
metadata
object
idempotencyKey
string

A retried request returns the original call rather than dialing the human twice.

Response

Success

object
string
required
Allowed value: "phone_call"
id
string<uuid>
required
direction
enum<string>
required
Available options:
outbound,
inbound
status
enum<string>
required

Terminal: completed, failed, no_answer, busy, canceled.

Available options:
queued,
initiating,
ringing,
in_progress,
completed,
failed,
no_answer,
busy,
canceled
fromNumber
string
required
toNumber
string
required
createdAt
string<date-time>
required
instructions
string | null
greeting
string | null
voice
string | null
model
string | null
language
string | null
backgroundAudio
enum<string> | null
Available options:
silence,
office,
none,
null
maxDurationSeconds
integer | null
queuedAt
string<date-time> | null
startedAt
string<date-time> | null
answeredAt
string<date-time> | null
endedAt
string<date-time> | null
durationSeconds
integer | null
hangupCause
string | null
answeredBy
string | null

human or machine, from answering-machine detection.

summary
string | null
costUsd
number | null

Billed per started minute.

error
string | null
webhookUrl
string | null
metadata
object
idempotencyKey
string | null