POST /calls
https://api.voygr.tech/calls
Overview
Place an outbound AI phone call. Send target_phone + brief for new calls. The structured shape (intent + slots) is deprecated and kept only for existing integrations; its responses carry Deprecation and Link headers, and the guide above covers its 422 slot-retry loop. Either shape takes the optional disclosure and record_call fields, which change or turn off the call's opening notice and its recording, and voice. A refusal below places no call and costs nothing. Two answers below are not refusals, because they cannot say whether a call was placed: 409 idempotency_state_unknown and 502. Their entries say how to recover.
Authentication
- API key in header
X-API-Key: Your customer API key (pk_live_...), sent on every request. Self-serve at https://api.voygr.tech/checkout.
Parameters
| Name | Location | Required | Type | Description and constraints |
|---|---|---|---|---|
Idempotency-Key | header | optional | string | null | Makes a retry safe: one fresh value (a UUID) per call you intend to place, in printable ASCII. For 24 hours the same key and body return the original response with the header Idempotent-Replayed: true, and nothing is dialed or charged again. After a 402, 429, 502, 503 or 403 account_suspended, retry with the same key; a 400, other 403 or 422 is replayed as is, so fix the body and use a new key. Without the header every request is a new call. length 1 to 255 |
X-Client-Surface | header | optional | string | Optional. Names the listing or document this call was placed from (for example llms-txt). Telemetry only: it never affects auth, billing or the call. max length 64 |
Request body
required
application/json
Schema: CallCreateRequest
Freeform brief
{
"target_phone": "+15551234567",
"brief": "Call and ask what time the kitchen closes tonight. Thank them and hang up.",
"language": "en"
}Structured slots (deprecated; use brief for new calls)
{
"target_phone": "+15551234567",
"intent": "inquiry",
"slots": {
"intent": "inquiry",
"target_phone": "+15551234567",
"question": "What time does the kitchen close tonight?"
}
}Responses
202
Call accepted and queued for dialing: the response api.voygr.tech gives to every accepted call. The body has a top-level call_id and status=queued: freeform returns QueuedCallResponse, which also repeats the ID as call.call_id, and structured returns SkillRunResponse. Take the top-level call_id (or call.call_id from a 201) and poll GET /calls/{call_id} for progress. A call over your concurrent-call limit is accepted the same way and waits in the queue until one of your calls ends; a call still queued after an hour fails and its hold is released.
application/json
Schema: QueuedCallResponse | SkillRunResponse
Freeform path, queued - QueuedCallResponse
{
"call_id": "c_abc123",
"position": 0,
"status": "queued",
"credits_reserved": 0,
"credits_charge_on_success": 10,
"call": {
"call_id": "c_abc123",
"status": "queued"
}
}Structured queued response; creditsreserved=0 does not mean no balance is held
{
"call_id": "c_abc123",
"status": "queued",
"credits_reserved": 0,
"status_url": "/calls/c_abc123",
"answer_url": "/calls/c_abc123/answer",
"recording_url": "/calls/c_abc123/recording",
"replayed": false,
"expected_next_steps": [
"..."
]
}201
Call created and dialing, returned only by a deployment that dials immediately (api.voygr.tech answers 202). The envelope depends on the request path: freeform returns CallResponse (a call wrapper, so the ID is call.call_id), structured returns the flat SkillRunResponse (top-level call_id). Either way, poll GET /calls/{call_id} afterwards; that response is the same whichever path created the call.
application/json
Schema: CallResponse | SkillRunResponse
Freeform path - CallResponse (call wrapper)
{
"call": {
"call_id": "c_abc123",
"customer_id": "cus_xyz",
"target_phone": "+15551234567",
"language": "en",
"status": "dialing",
"started_at": null,
"ended_at": null,
"duration_sec": null,
"outcome_type": null,
"outcome_summary": null,
"outcome_charge_cents": 0,
"created_at": "2026-07-17T12:00:00Z",
"has_recording": false,
"recording_url": null,
"reservation_signals": null,
"transcript_full": null,
"transcript_status": null
},
"credits_reserved": 0,
"credits_charge_on_success": 10
}Structured path - SkillRunResponse (flat, no wrapper)
{
"call_id": "c_abc123",
"status": "dialing",
"credits_reserved": 0,
"credits_charge_on_success": 10,
"status_url": "/calls/c_abc123",
"answer_url": "/calls/c_abc123/answer",
"recording_url": "/calls/c_abc123/recording",
"replayed": false,
"expected_next_steps": [
"..."
]
}400
Idempotency-Key is empty, over 255 characters or not printable ASCII. Nothing was dialed.
application/json
idempotencykeyinvalid
{
"detail": {
"error": "idempotency_key_invalid",
"message": "Idempotency-Key must be between 1 and 255 characters."
}
}Refused at the gateway
{
"detail": {
"error": "invalid Idempotency-Key header: must be printable ASCII, at most 256 characters"
}
}401
Missing or invalid X-API-Key.
application/json
X-API-Key header absent
{
"detail": {
"error": "API key required"
}
}X-API-Key doesn't resolve to an active key
{
"detail": {
"error": "invalid API key"
}
}402
Insufficient credits for the 30-credit refundable hold.
application/json
Insufficient available credits
{
"detail": {
"error": "quota_exceeded",
"needed_credits": 30,
"checkout_url": "/checkout/buy"
}
}403
Key not permitted to make this request, or the account is suspended (account_suspended: adding credits does not clear it; contact support).
application/json
accountsuspended
{
"detail": {
"error": "account_suspended",
"message": "This account is suspended. No call was placed and nothing was charged. Contact support to reactivate it."
}
}tiernotpermitted
{
"detail": {
"error": "tier not permitted"
}
}missingentitlement
{
"detail": {
"error": "missing entitlement: booking"
}
}Freeform brief disabled for this key
{
"detail": {
"error_code": "freeform_disabled",
"hint": "Submit structured `slots` (see GET /skills) or ask ops to enable freeform for this key."
}
}409
Idempotency-Key conflict. idempotency_conflict: an earlier request used the same key with a different body; use a new key. idempotency_in_progress: a request with it is still running; wait detail.retry_after_seconds, then retry with the same key and body. idempotency_state_unknown: the first request stopped without recording whether the call was placed; look for it in GET /calls, then keep it or retry with a new key. The concurrent-call limit does not return 409: a call over it is accepted with 202 and waits in the queue.
application/json
idempotencyconflict
{
"detail": {
"error": "idempotency_conflict",
"message": "An earlier request used this Idempotency-Key with a different body. Use a fresh key for this new call."
}
}idempotencyinprogress
{
"detail": {
"error": "idempotency_in_progress",
"message": "An earlier request with this Idempotency-Key is still running. Retry after the indicated delay.",
"retry_after_seconds": 2
}
}422
Refused before anything was dialed, keyed on detail.error_code (some bodies repeat it as detail.error). Request: missing_target_phone, invalid_target_phone (not E.164; a bare 10-digit number needs its +1), missing_brief, unsupported_language. Destination: emergency_code_blocked (911), service_code_blocked (other N11 codes), premium_rate_blocked, dial_control_syntax_blocked, region_not_supported, destination_unattributable, destination_unscannable, destination_blocked; do not retry these numbers. Brief: brief_policy_violation (the brief asks for something calls may not do). Structured path: missing_slots, invalid_slots, unknown_intent. Opening notice: principal_conflict, recording_contradiction, disclosure_invalid_text, disclosure_unsupported_language, disclosure_too_long. ask_user_mode webhook with no webhook registered: ask_user_channel_required (detail.error). suggestion_id: SUGGESTION_NOT_FOUND, SUGGESTION_PHONE_MISMATCH, SUGGESTION_WITH_SLOTS_UNSUPPORTED. Anything else (wrong types, an unknown key inside disclosure or voice, disclosure: true, a brief over 4000 characters) is the standard validation list.
application/json
Freeform path without targetphone
{
"detail": {
"error_code": "missing_target_phone",
"hint": "Provide `target_phone` (E.164) on the freeform path, or use `slots` (structured)."
}
}Freeform path, brief absent/empty
{
"detail": {
"error_code": "missing_brief",
"hint": "Provide `brief` (freeform) or `slots` (structured) - see GET /skills/concierge/manifest."
}
}Structured path, required slots absent (flagship retry loop)
{
"detail": {
"error_code": "missing_slots",
"slot_schema_version": "concierge-v1",
"intent_type": "inquiry",
"missing_slots": [
{
"slot_name": "question",
"reason": "the single question the agent must ask the venue",
"suggested_question": "What should we ask them?",
"type_hint": "free_text"
}
],
"invalid": {},
"hint": "Collect the listed slots from your user and resubmit with `slots` populated."
}
}A free-text slot exceeds 2000 characters
{
"detail": {
"error_code": "invalid_slots",
"slot_schema_version": "concierge-v1",
"invalid": {
"question": "must be at most 2000 characters"
},
"hint": "Shorten the listed free-text slots to at most 2000 characters and resubmit."
}
}Opening notice: mentionrecording true with recordcall false
{
"detail": {
"error_code": "recording_contradiction",
"error": "recording_contradiction",
"hint": "`mention_recording: true` says the call is recorded and `record_call: false` means it is not."
}
}Opening notice: the sentence would be over 180 characters
{
"detail": {
"error_code": "disclosure_too_long",
"error": "disclosure_too_long",
"hint": "The opening sentence would be 196 characters; the limit is 180. Shorten an element."
}
}Destination in a region we do not call (a country not served, or IN, LA, MN, MT, NE)
{
"detail": {
"error": "region_not_supported",
"error_code": "region_not_supported",
"blocked_code": "US-IN",
"message": "Calls to this destination are not supported.",
"hint": "Do not retry this number."
}
}askusermode webhook, no webhook registered
{
"detail": {
"error": "ask_user_channel_required",
"message": "ask_user_mode=\"webhook\" requires a webhook on this API key, and none is configured. Set one with PUT /users/me/webhook, or send ask_user_mode=\"any\" to receive mid-call questions on GET /calls/{call_id}/events instead.",
"missing_channels": [
"webhook"
]
}
}Standard field validation, e.g. a non-string brief
{
"detail": [
{
"type": "string_type",
"loc": [
"body",
"brief"
],
"msg": "Input should be a valid string",
"input": 12345
}
]
}429
Rate limit exceeded; wait and follow Retry-After when returned. Free keys are limited to 10 requests per second and 120 requests per minute, and can place 1 call at a time, up to 25 calls per day. Paid keys are limited to 10 requests per second and 120 requests per minute. A top-up raises a key's daily cap to 5,000 calls and its concurrent-call ceiling to 10. Enterprise limits are set per contract. With detail.error daily_call_ceiling_reached, this account has created its calls for the UTC day (max_calls_per_day on GET /users/me); retry after detail.resets_at. global_daily_call_ceiling_reached is the same refusal for the whole service. Nothing was dialed or charged.
application/json
ratelimited
{
"detail": {
"error": "rate limit exceeded"
}
}dailycallceilingreached
{
"detail": {
"error": "daily_call_ceiling_reached",
"error_code": "daily_call_ceiling_reached",
"limit": 100,
"used": 100,
"resets_at": "2026-08-01T00:00:00+00:00",
"message": "...",
"hint": "..."
}
}502
The call could not be started or queued. A 502 is not proof that no call was placed: retry with the same Idempotency-Key and body.
application/json
backenderror
{
"error": "backend error",
"error_code": "BACKEND_ERROR"
}503
Service in a maintenance window (maintenance, with resume_at), or a check the call needs is briefly unavailable (brief_guard_unavailable, daily_call_ceiling_unavailable, dial_policy_unavailable): nothing was dialed; retry shortly.
application/json
maintenance
{
"detail": {
"error": "maintenance",
"message": "...",
"resume_at": "2026-07-17T13:00:00Z"
}
}Schemas
CallCreateRequest
Type: object
Send target_phone + brief (+ optional language) for new calls. The structured shape, intent + slots (one of inquiry, info_gathering, issue_resolution, booking), is deprecated and kept only for existing integrations; it reads slots.target_phone instead of target_phone.
| Field | Type | Required | Description and constraints | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ask_user_mode | string | optional | A mid-call question always goes to the ask_user event on GET /calls/{call_id}/events. When this key has a webhook registered whose events include ask_user (the default), it also goes to a signed POST to it, with the same request_id. Answer via POST /calls/{call_id}/answer. any (default) and stream behave the same. webhook adds a check before dialing: with no webhook registered on this key the call is refused with 422 ask_user_channel_required. one of any, stream, webhook; default any | ||||||||||||
brief | string (max length 4000) | null | optional | Plain-language task for the call. Required for freeform requests. | ||||||||||||
disclosure | DisclosureBody | boolean | null | optional | Shape the sentence the call opens with, or switch it off. Absent: the default sentence ("Hi, this is PlaceCall's AI assistant, calling for a client on a recorded line." in English). An object: the sentence is built from its elements (English and Spanish calls only; a freeform call with language: auto opens in English; at most 180 characters in all). false: no opening notice. The agent opens with a short greeting and your request and says who is calling only when asked, and you must give every notice the law requires yourself. true is refused with 422. You are responsible for the notice your calls give meeting the law that applies to them. | ||||||||||||
intent | string (one of inquiry, info_gathering, issue_resolution, booking) | null | optional | Deprecated: send a freeform brief instead. Structured path only. booking places the call to make the reservation; no booking record is stored. | ||||||||||||
items | array of object | null | optional | Optional. The things the call must find out or get done, each as {"id", "ask"}: id is your own key (1-64 characters of letters, digits, _, ., -, unique in the request) and ask is one plain-language question or task (1-120 characters). At most 12 items. Stored with the call and echoed in the response; an item that breaks a rule is refused with 422 (too_many_items, item_too_long, items_invalid, items_duplicate), never trimmed. Freeform path only.Option 1 fields item fields
| ||||||||||||
kind | TaskKind | optional | Optional freeform task category; brief defines the task. Ignored for structured requests, which use intent. default other | ||||||||||||
language | string | optional | ISO 639-1 code or auto. Unsupported codes are refused with 422 unsupported_language.one of auto, de, en, es, fr, hi, it, ja, nl, pl, pt, ru, sr, tr; default auto | ||||||||||||
record_call | boolean | null | optional | false: the call's audio is never recorded and the opening sentence drops its recording clause; transcript_full is still kept, and transcript_status reads final as soon as the transcript exists. Default true. Outside English and Spanish, false requires disclosure: false, because those default sentences announce a recorded line. | ||||||||||||
slots | object | null | optional | Deprecated: send a freeform brief instead. Structured path only. Required slots per intent. inquiry: target_phone, question. info_gathering: target_phone, questions. issue_resolution: target_phone, issue_description. booking: target_phone, name, date (YYYY-MM-DD), time (HH:MM, 24-hour), party_size. | ||||||||||||
suggestion_id | string (length 4 to 40) | null | optional | Links this call to a card from POST /v1/places/suggest. Freeform path only. The card must be yours and at most 7 days old, and target_phone must equal its phone_e164; otherwise 422 SUGGESTION_NOT_FOUND, SUGGESTION_PHONE_MISMATCH or SUGGESTION_WITH_SLOTS_UNSUPPORTED. It changes nothing about how the call is placed. | ||||||||||||
target_phone | string (length 3 to 32) | null | optional | E.164 format. Example: "+15551234567" | ||||||||||||
voice | VoiceBody | null | optional | How the agent sounds, for example {"gender": "female"}. Absent: the default voice for the call's language. Best effort: it never fails the call. |
QueuedCallResponse
Type: object
Freeform call accepted with 202 and queued for dialing, the normal response on api.voygr.tech; the call ID is the top-level call_id, repeated as call.call_id. Poll GET /calls/{call_id} until status leaves queued. Structured requests use SkillRunResponse instead.
| Field | Type | Required | Description and constraints | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
call | QueuedCallRef | required | The same call_id and status, nested as in the 201 body, for clients that read call.call_id. | ||||||||||||||||||||
call_id | string | required | Example: "c_abc123" | ||||||||||||||||||||
credits_charge_on_success | integer | optional | What a charged call costs: 10 credits. A PlaceCall call costs 10 credits when it obtains something (an answer, a refusal or a booking). Each call holds 30 credits while it runs, and the unused part is released. A call that obtains nothing is free, and so is a cancel within 30 seconds of the callee answering; a cancel 30 seconds or more after pickup is charged 10 credits. default 0 Example: 10 | ||||||||||||||||||||
credits_reserved | integer | optional | Reported call-local reservation, not the final charge or available balance. It is 0 for calls through api.voygr.tech; a separate refundable balance hold still applies. Read GET /v1/usage for available credits and call_credit_hold. default 0 Example: 0 | ||||||||||||||||||||
items | array of EchoedItem | null | optional | The items the request sent, in its order. When it sent none: the items the pre-dial read derived from the brief (PREDIAL_GAP_MODE warn|enforce), or null. | ||||||||||||||||||||
position | integer | required | Queue position; 0 is the front. Another call may still be starting when this is 0. Example: 0 | ||||||||||||||||||||
status | string | optional | one of queued; default queued | ||||||||||||||||||||
warnings | array of object | optional | What the pre-dial read of the brief found. Present on every body from a deployment where the read is on (an empty list when there is nothing to say); absent where it is off. Never a refusal: the call was placed or queued.Item fields
|
SkillRunResponse
Type: object
Structured call success envelope with top-level call_id and no call wrapper. A 201 means dialing started; a 202 has status=queued. Poll status_url (GET /calls/{call_id}) for progress.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
answer_url | string | required | Example: "/calls/c_abc123/answer" |
call_id | string | required | Example: "c_abc123" |
credits_charge_on_success | integer | optional | What a charged call costs: 10 credits. A PlaceCall call costs 10 credits when it obtains something (an answer, a refusal or a booking). Each call holds 30 credits while it runs, and the unused part is released. A call that obtains nothing is free, and so is a cancel within 30 seconds of the callee answering; a cancel 30 seconds or more after pickup is charged 10 credits. default 0 Example: 10 |
credits_reserved | integer | required | Reported call-local reservation, not the final charge or available balance. It is 0 for calls through api.voygr.tech; a separate refundable balance hold still applies. Read GET /v1/usage for available credits and call_credit_hold. Example: 0 |
expected_next_steps | array of string | required | |
recording_url | string | required | Relative path /calls/{call_id}/recording. Present even before a recording exists, unlike CallDTO.recording_url. Example: "/calls/c_abc123/recording" |
replayed | boolean | optional | default False |
status | string | required | one of scheduled, queued, dialing, in_progress, completed, failed, cancelled |
status_url | string | required | Same as GET /calls/{call_id}. Example: "/calls/c_abc123" |
CallResponse
Type: object
Freeform 201 envelope, returned only by a deployment that dials immediately; the call ID is call.call_id. api.voygr.tech queues every call and answers 202 with QueuedCallResponse instead. Poll GET /calls/{call_id} for progress.
| Field | Type | Required | Description and constraints | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
call | CallDTO | required | |||||||||||||||||||||
credits_charge_on_success | integer | required | What a charged call costs: 10 credits. A PlaceCall call costs 10 credits when it obtains something (an answer, a refusal or a booking). Each call holds 30 credits while it runs, and the unused part is released. A call that obtains nothing is free, and so is a cancel within 30 seconds of the callee answering; a cancel 30 seconds or more after pickup is charged 10 credits. Example: 10 | ||||||||||||||||||||
credits_reserved | integer | required | Reported call-local reservation, not the final charge or available balance. It is 0 for calls through api.voygr.tech; a separate refundable balance hold still applies. Read GET /v1/usage for available credits and call_credit_hold. Example: 0 | ||||||||||||||||||||
items | array of EchoedItem | null | optional | The items the request sent, in its order. When it sent none: the items the pre-dial read derived from the brief (PREDIAL_GAP_MODE warn|enforce), or null. | ||||||||||||||||||||
warnings | array of object | optional | What the pre-dial read of the brief found. Present on every body from a deployment where the read is on (an empty list when there is nothing to say); absent where it is off. Never a refusal: the call was placed or queued.Item fields
|
DisclosureBody
Type: object
The elements of the call's opening sentence. Every field is optional; an unknown field is refused with 422 rather than ignored. The example speaks "Hi, this is Acme Health's AI assistant, calling for Example Insurance on a recorded line to verify your practice's directory information."
| Field | Type | Required | Description and constraints |
|---|---|---|---|
company_name | string (max length 60) | null | optional | Who is calling: "Hi, this is {company_name}". Default "PlaceCall". It must be your own business or one you are authorized to represent: the terms of service prohibit impersonation. |
mention_ai | boolean | optional | Say the caller is an AI assistant: "{company_name}'s AI assistant". false drops it.default True |
mention_recording | boolean | null | optional | Include "on a recorded line". Defaults to the value of record_call; true with record_call: false is refused. |
on_behalf_of | string (max length 80) | null | optional | On whose behalf: "calling for {on_behalf_of}". Must match caller_display_name when both are sent. |
purpose | string (max length 100) | null | optional | Ends the sentence, e.g. "to verify your practice's directory information". One clause: no . ! ? or ;. Spoken exactly as sent, so write it in the call's language. |
Example
{
"company_name": "Acme Health",
"on_behalf_of": "Example Insurance",
"purpose": "to verify your practice's directory information",
"mention_ai": true
}TaskKind
Type: string
one of restaurant_booking, restaurant_cancel, doctor_appointment, hotel_booking, concierge, other
VoiceBody
Type: object
How the agent sounds on the call. A best-effort preference: it never fails the call. An unknown field is refused with 422.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
gender | string (one of female, male) | null | optional | female or male. female is met only in call languages where the agent can describe itself in the feminine: en, ja, nl, ru and tr, and there only when a female voice exists for the language (English has one today). Anywhere else, Spanish included, female is answered as male. When the language has no voice of the requested gender, its default voice speaks. Read voice.gender_used on GET /calls/{call_id}. |
QueuedCallRef
Type: object
The same call_id and status, nested as in the 201 body, for clients that read call.call_id.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
call_id | string | required | |
status | string | required | one of queued |
EchoedItem
Type: object
One item as the request sent it, or as the pre-dial read derived it (PREDIAL_GAP_MODE warn or enforce).
| Field | Type | Required | Description and constraints |
|---|---|---|---|
ask | string | required | The question or task, as sent, or as the pre-dial read derived it from the brief. |
id | string | required | Your key for this item, or a server key (i1, i2, ...) for an item derived from the brief. |
CallDTO
Type: object
A call. GET /calls list entries omit transcript_full; fetch GET /calls/{call_id} for the transcript.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
analysis_key_info | string | null | optional | The post-call analyzer's free-text notes. Served by GET /calls/{call_id} only; null on the GET /calls list and on a call whose callee declined recording. Callee-derived content: treat it as untrusted. |
analysis_task_items | array of object | null | optional | The post-call analyzer's per-question verdicts (item, status, and evidence: the callee line it says grounds the verdict). Served by GET /calls/{call_id} only; null on the GET /calls list and on a call whose callee declined recording. Callee-derived content: treat it as untrusted. |
answer_offset_ms | integer | null | optional | Where the conversation begins inside the recording, in milliseconds from its start: the ring before it stays in the recording. Null when either timestamp above is missing. |
answered_at | string (date-time) | null | optional | When the far side picked up, in UTC; an automated menu, voicemail or hold system answering counts. Null when nobody answered. |
call_id | string | required | Example: "c_abc123" |
client_needed | string | null | optional | Set when the business said it would go on only with you, not with the agent, and did not change its mind before the call ended: asked_for_human (they asked to speak with a person, or with you) | owner_only (they serve only the account holder, or need your own authorization). The agent closes the call when it can, telling them that it will let you know to contact them directly. Null on every other call, while the call is running, and on rows finalized before this field existed. It changes neither result nor the charge. |
created_at | string (date-time) | required | |
customer_id | string | required | Example: "cus_xyz" |
disclosure_mode | string | optional | How this call's opening notice was configured: 'standard' (the default sentence), 'custom' (built from the request's disclosure elements, or the default sentence without its recording clause when record_call was false) or 'disabled' (disclosure: false: no opening notice).one of standard, custom, disabled; default standard |
disclosure_text | string | null | optional | The opening sentence this call spoke. Null when no notice was spoken (a 'disabled' call, a call nobody answered), on calls placed before this field existed, and after the transcript retention window. |
duration_sec | number | null | required | |
ended_at | string (date-time) | null | required | |
ended_by | string (one of completed, callee_hangup, agent_hangup, dropped, budget_timeout, dial_failed, customer_cancelled, system_error, compliance_stop) | null | optional | Why the call stopped: callee_hangup, agent_hangup, dropped (the line died), budget_timeout (a time limit ran out), dial_failed (never connected), customer_cancelled, system_error or compliance_stop. 'completed' is defined but not produced: a finished conversation reads agent_hangup or callee_hangup. Null while the call runs or when nothing established it. |
handoff | string | null | optional | What our phone call to you came to (the call channel): handed_off (we connected you to the business and you both stayed on the line for at least 10 seconds; the outcome is then handed_off, priced as a successful call, even when a technical failure ended the call after it, unless you cancelled the call, the recording notice failed or the call reached the wrong party) | attempted_failed (any other attempt: no answer, not accepted, a connection that failed or held under 10 seconds; the call is judged as usual and this adds nothing to the charge). Null when we never phoned you, while the call is running, and on rows finalized before this field existed. |
has_recording | boolean | optional | default False |
language | string | required | |
line_kind | string (one of human, voicemail, ivr, no_answer, recorded_announcement, hold_queue) | null | optional | What was on the line: human, voicemail, ivr (a phone menu that never reached a person), no_answer (nobody picked up, or busy), recorded_announcement or hold_queue (a queue no agent answered). Null on an aborted call and while the call runs. |
outcome_charge_cents | integer | required | Settled charge in credits, despite the field name; not the refundable hold. A PlaceCall call costs 10 credits when it obtains something (an answer, a refusal or a booking). Each call holds 30 credits while it runs, and the unused part is released. A call that obtains nothing is free, and so is a cancel within 30 seconds of the callee answering; a cancel 30 seconds or more after pickup is charged 10 credits. |
outcome_summary | string | null | required | |
outcome_type | string (one of success_booked, success_refused, success_no_booking, success_booking_cancelled, handed_off, failed_voicemail, failed_no_answer, failed_busy, failed_short_hangup, failed_technical, failed_no_agent_available, failed_ivr_no_agent, failed_recorded_announcement, failed_no_disclosure, failed_call_dropped, failed_wrong_number, failed_cancelled, failed_no_engagement, failed_agent_mute, failed_language_barrier) | null | optional | Deprecated: read result, line_kind and result_reason (and ended_by for why the call stopped). Still returned once the call is terminal, with no removal date. Its success_/failed_ prefix is a billing family, not the charge: read outcome_charge_cents. failed_no_agent_available means no human answered before the call's hold-time limit. success_booking_cancelled and failed_language_barrier are defined but not produced yet. |
record_call | boolean | optional | False when the call was placed with record_call: false: no audio was captured, so no recording is checked and transcript_status reads final as soon as the transcript exists.default True |
recording_declined | boolean | optional | True when the callee refused call recording. Such a call never gets a verbatim record: transcript_full and transcript_status stay null permanently, so do not wait for a transcript. outcome_type and outcome_summary are unaffected. default False |
recording_started_at | string (date-time) | null | optional | When the call's recording began, in UTC. It starts before the phone rings, so it is earlier than answered_at by about the ring time. Null when nothing was recorded or the recording is not finalized yet. |
recording_status | string | optional | What is known about the call's audio: available (a recording exists; has_recording is true exactly here), pending (the call is running or the recording is still finalizing), delayed (the usual finalization window has passed; not a final answer), declined (the callee refused recording) or not_recorded (placed with record_call: false; it outranks declined). one of available, pending, delayed, declined, not_recorded; default pending |
recording_url | string | null | optional | Relative recording path /calls/{call_id}/recording when a recording exists; null when has_recording is false. Recording retrieval is not documented here. |
reservation_signals | array of string | null | optional | Short free-text signals (<10 short strings) about the reservation outcome. Always included, unlike transcript_full. |
result | string (one of goal_met, goal_partial, refused, goal_not_met, wrong_party, not_reached, aborted, pending) | null | optional | Did the call get what it was placed for. goal_met: everything the brief asked. goal_partial: some of it. refused: they understood and declined. goal_not_met: reached them, got nothing. wrong_party: answered, but not the business asked for. not_reached: nobody able to answer was on the line. aborted: stopped by an error, a compliance stop or your cancel. pending: something on the call waits on someone (reserved; not returned yet). Read any value you do not know as unfinished. Null while the call runs. Read outcome_charge_cents for the charge. |
result_reason | string (one of booked, booking_cancelled, call_dropped, short_hangup, no_engagement, agent_mute, language_barrier, busy, system_error, customer_cancelled, no_disclosure, handed_off) | null | optional | The specific reason behind result where result alone is shared: booked, booking_cancelled, call_dropped, short_hangup, no_engagement, agent_mute, language_barrier, busy, system_error, customer_cancelled, no_disclosure or handed_off (your client joined the call by phone). Null where result and line_kind already say everything (a refusal, a voicemail, an answered question) and while the call runs. |
started_at | string (date-time) | null | required | |
status | string | required | one of scheduled, queued, dialing, in_progress, completed, failed, cancelled |
target_phone | string | required | Example: "+15551234567" |
transcript_full | array of TranscriptTurn | null | optional | The call's transcript: what the agent heard and the agent speech that played. Only populated on GET /calls/{call_id}, not on the GET /calls list. While transcript_status reads live, a post-call check of the recording can still add audio to operator rows and add heard: false rows. Null while no transcript is held: the call has not finished, the callee declined recording (recording_declined), or the call is past retention or erased. [] means the agent heard nothing and none of its speech played; such a call can still gain heard: false rows. Calls finalized before the 21 October 2026 release have the same row keys but not the newer row details. There is no confidence, bot rows show the whole generated reply (in rare cases one that never played), and interrupted can also mark a reply cut by the end of the call. |
transcript_status | string (one of live, final) | null | optional | live while a post-call check of the call recording is still expected; the check can add audio to rows and add heard: false rows. final once the check has run or is no longer expected: the call was placed with record_call: false, its recording may not be sent for the check because a required opening notice was not delivered, or 30 minutes passed after the call ended without it. A final status says nothing about whether any row was corrected. Null exactly when transcript_full is. The check usually lands one to two minutes after the call ends. To read the complete transcript, poll GET /calls/{call_id} until this reads final. On a call with recording_declined: true it stays null for good, so stop polling there. |
voice | CallVoiceDTO | optional | The voice this call asked for, and the voice that spoke. |
TranscriptTurn
Type: object
One row of the call's transcript: something the agent heard (operator rows), agent speech that played (bot rows) or what the person we phoned in said after joining (client rows). A row has only these keys. Rows are in emission order; sort by ts for chronological order.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
audio | TranscriptAudio | optional | |
confidence | number | optional | operator rows: the recognizer's mean per-word confidence for text. Absent where it is not known, such as on a salvaged row. 0.0 to 1.0 |
heard | boolean | optional | Present, and false, only on a row the post-call check of the recording added: speech on the recording the agent likely missed. Such a row is an operator row with no text and audio.kind unheard. |
interrupted | boolean | optional | bot rows, present only as true. Either the callee cut in while the reply played, so they heard only part of it, or the reply was cut and the played words are not known. In that case text is the whole reply. |
role | string | optional | operator = whoever or whatever answered (a person, a voicemail greeting, a phone menu); bot = the agent; client = the person we phoned in through the call escalation channel, once they joined (see handoff).one of operator, bot, client |
salvaged | boolean | optional | Present, and true, only on a row recovered from an unfinalized speech-to-text interim when the call ended mid-utterance. The text is real but slightly less reliable. |
text | string | optional | operator rows: the live speech-to-text final the agent acted on, never rewritten. bot rows: the words that played; a reply that never played is not served. Absent on a heard: false row. |
ts | number | optional | Epoch seconds. The instant depends on the row. An operator row: when the speech-to-text final arrived (the end of the utterance plus the recognizer's end-of-turn delay). A salvaged row: when the turn started. A heard: false row: the end of the utterance on the recording. A model reply of the agent: when its text was generated, before it played. A fixed line of the agent: an estimate of when it became audible. The opening notice: when it finished playing. |
CallVoiceDTO
Type: object
The voice this call asked for, and the voice that spoke.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
gender | string (one of female, male) | null | optional | The voice.gender the request asked for; null when it asked for none. |
gender_used | string (one of female, male) | null | optional | The gender of the voice that spoke. Null until the call's audio starts. It differs from gender when no voice of that gender exists for the call's language, or when female was answered as male. |
TranscriptAudio
Type: object
operator rows only. What the call recording says for that stretch of speech, from the post-call check. On a row the agent heard, it appears only where the recording has a different number, yes or no, or name from the call's request. Differences in other words are not marked. Read it next to the row's own text, which is what the agent acted on. It appears only after the check has run (see transcript_status).
| Field | Type | Required | Description and constraints |
|---|---|---|---|
kind | string | required | name, number or yes_no on a row where the recording differs; unheard on a heard: false row. one of name, number, yes_no, unheard |
text | string | required | The recording's reading of the speech. |
On this page
