Skip to content

Place a call

POST /calls

https://api.voygr.tech/calls

Open in playground

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

NameLocationRequiredTypeDescription and constraints
Idempotency-Keyheaderoptionalstring | nullMakes 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-SurfaceheaderoptionalstringOptional. 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.

FieldTypeRequiredDescription and constraints
ask_user_modestringoptionalA 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
briefstring (max length 4000) | nulloptionalPlain-language task for the call. Required for freeform requests.
disclosureDisclosureBody | boolean | nulloptionalShape 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.
intentstring (one of inquiry, info_gathering, issue_resolution, booking) | nulloptionalDeprecated: send a freeform brief instead. Structured path only. booking places the call to make the reservation; no booking record is stored.
itemsarray of object | nulloptionalOptional. 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

FieldTypeRequiredDescription and constraints
askstringrequiredThe question or task, as sent.
length 1 to 120
idstringrequiredYour key for this item.
pattern `^[A-Za-z0-9_.-]{1,64}$`
kindTaskKindoptionalOptional freeform task category; brief defines the task. Ignored for structured requests, which use intent.
default other
languagestringoptionalISO 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_callboolean | nulloptionalfalse: 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.
slotsobject | nulloptionalDeprecated: 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_idstring (length 4 to 40) | nulloptionalLinks 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_phonestring (length 3 to 32) | nulloptionalE.164 format.
Example: "+15551234567"
voiceVoiceBody | nulloptionalHow 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.

FieldTypeRequiredDescription and constraints
callQueuedCallRefrequiredThe same call_id and status, nested as in the 201 body, for clients that read call.call_id.
call_idstringrequiredExample: "c_abc123"
credits_charge_on_successintegeroptionalWhat 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_reservedintegeroptionalReported 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
itemsarray of EchoedItem | nulloptionalThe 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.
positionintegerrequiredQueue position; 0 is the front. Another call may still be starting when this is 0.
Example: 0
statusstringoptionalone of queued; default queued
warningsarray of objectoptionalWhat 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

FieldTypeRequiredDescription and constraints
codestringrequiredAn open list: tolerate new codes.
itemsarray of stringoptionalThe item ids it concerns.
messagestringrequired
needstringoptionalWhat is missing, from the documented need list.

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.

FieldTypeRequiredDescription and constraints
answer_urlstringrequiredExample: "/calls/c_abc123/answer"
call_idstringrequiredExample: "c_abc123"
credits_charge_on_successintegeroptionalWhat 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_reservedintegerrequiredReported 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_stepsarray of stringrequired
recording_urlstringrequiredRelative path /calls/{call_id}/recording. Present even before a recording exists, unlike CallDTO.recording_url.
Example: "/calls/c_abc123/recording"
replayedbooleanoptionaldefault False
statusstringrequiredone of scheduled, queued, dialing, in_progress, completed, failed, cancelled
status_urlstringrequiredSame 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.

FieldTypeRequiredDescription and constraints
callCallDTOrequired
credits_charge_on_successintegerrequiredWhat 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_reservedintegerrequiredReported 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
itemsarray of EchoedItem | nulloptionalThe 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.
warningsarray of objectoptionalWhat 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

FieldTypeRequiredDescription and constraints
codestringrequiredAn open list: tolerate new codes.
itemsarray of stringoptionalThe item ids it concerns.
messagestringrequired
needstringoptionalWhat is missing, from the documented need list.

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."

FieldTypeRequiredDescription and constraints
company_namestring (max length 60) | nulloptionalWho 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_aibooleanoptionalSay the caller is an AI assistant: "{company_name}'s AI assistant". false drops it.
default True
mention_recordingboolean | nulloptionalInclude "on a recorded line". Defaults to the value of record_call; true with record_call: false is refused.
on_behalf_ofstring (max length 80) | nulloptionalOn whose behalf: "calling for {on_behalf_of}". Must match caller_display_name when both are sent.
purposestring (max length 100) | nulloptionalEnds 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.

FieldTypeRequiredDescription and constraints
genderstring (one of female, male) | nulloptionalfemale 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.

FieldTypeRequiredDescription and constraints
call_idstringrequired
statusstringrequiredone 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).

FieldTypeRequiredDescription and constraints
askstringrequiredThe question or task, as sent, or as the pre-dial read derived it from the brief.
idstringrequiredYour 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.

FieldTypeRequiredDescription and constraints
analysis_key_infostring | nulloptionalThe 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_itemsarray of object | nulloptionalThe 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_msinteger | nulloptionalWhere 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_atstring (date-time) | nulloptionalWhen the far side picked up, in UTC; an automated menu, voicemail or hold system answering counts. Null when nobody answered.
call_idstringrequiredExample: "c_abc123"
client_neededstring | nulloptionalSet 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_atstring (date-time)required
customer_idstringrequiredExample: "cus_xyz"
disclosure_modestringoptionalHow 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_textstring | nulloptionalThe 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_secnumber | nullrequired
ended_atstring (date-time) | nullrequired
ended_bystring (one of completed, callee_hangup, agent_hangup, dropped, budget_timeout, dial_failed, customer_cancelled, system_error, compliance_stop) | nulloptionalWhy 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.
handoffstring | nulloptionalWhat 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_recordingbooleanoptionaldefault False
languagestringrequired
line_kindstring (one of human, voicemail, ivr, no_answer, recorded_announcement, hold_queue) | nulloptionalWhat 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_centsintegerrequiredSettled 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_summarystring | nullrequired
outcome_typestring (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) | nulloptionalDeprecated: 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_callbooleanoptionalFalse 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_declinedbooleanoptionalTrue 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_atstring (date-time) | nulloptionalWhen 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_statusstringoptionalWhat 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_urlstring | nulloptionalRelative recording path /calls/{call_id}/recording when a recording exists; null when has_recording is false. Recording retrieval is not documented here.
reservation_signalsarray of string | nulloptionalShort free-text signals (<10 short strings) about the reservation outcome. Always included, unlike transcript_full.
resultstring (one of goal_met, goal_partial, refused, goal_not_met, wrong_party, not_reached, aborted, pending) | nulloptionalDid 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_reasonstring (one of booked, booking_cancelled, call_dropped, short_hangup, no_engagement, agent_mute, language_barrier, busy, system_error, customer_cancelled, no_disclosure, handed_off) | nulloptionalThe 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_atstring (date-time) | nullrequired
statusstringrequiredone of scheduled, queued, dialing, in_progress, completed, failed, cancelled
target_phonestringrequiredExample: "+15551234567"
transcript_fullarray of TranscriptTurn | nulloptionalThe 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_statusstring (one of live, final) | nulloptionallive 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.
voiceCallVoiceDTOoptionalThe 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.

FieldTypeRequiredDescription and constraints
audioTranscriptAudiooptional
confidencenumberoptionaloperator 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
heardbooleanoptionalPresent, 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.
interruptedbooleanoptionalbot 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.
rolestringoptionaloperator = 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
salvagedbooleanoptionalPresent, 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.
textstringoptionaloperator 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.
tsnumberoptionalEpoch 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.

FieldTypeRequiredDescription and constraints
genderstring (one of female, male) | nulloptionalThe voice.gender the request asked for; null when it asked for none.
gender_usedstring (one of female, male) | nulloptionalThe 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).

FieldTypeRequiredDescription and constraints
kindstringrequiredname, number or yes_no on a row where the recording differs; unheard on a heard: false row.
one of name, number, yes_no, unheard
textstringrequiredThe recording's reading of the speech.