Calls
Create, track, and read single-target calls.
Create Call
Prepare one phone task, then return 202 after durable acceptance. Dialing runs in the background; acceptance does not prove connection or business success. Region and locale are optional or null. Infer region from the phone and spoken locale from task intent and supported regional languages; responses contain the resolved values. Explicit locale is preserved. Conflicting phone/region or ambiguous language returns 422 input_incomplete with details.missing_inputs; phone/region conflicts also include details.fields, region and inferred_region. Unsupported targets return 422 unsupported_region or unsupported_language with details.field, region and locale. Explicit targets are checked before preparation; inferred locale is checked after inference. These rejections create no Call. Unsupported result_schema types, including nullable unions, return 400 result_schema_invalid. Preparation is bounded to 25 seconds; configuration access failures, conflicting profiles, model failures or timeouts return 503 provider_unavailable. Accepted instructions and input are immutable and reused on replay. Calls accept one phone and immediate execution only: no batch recipients, scheduling, recurrence or recipient_result_schema.
Headers
Idempotency-KeyPersist one key and the original request per logical call. Same project, authenticated owner, key and input return 202 with the original Call ID and its current saved state, including after completion, failure or cancellation. Replay does not prepare or dial again. An intentionally new call requires a new key. Changes to task, phone, region, locale, result_schema, metadata or webhook_url return 409 idempotency_conflict; JSON object-key order is not significant. Keep omitted region/locale omitted on retries; adding inferred response values changes the input. Concurrent creation returns 409 idempotency_conflict with details.reason_code=creation_in_progress: back off and retry unchanged. A definitive validation rejection before acceptance creates no Call and permits corrected input with the same key. After a timeout or uncertain response, reuse the original key and body, not a new key. Keys must be 1-255 characters after trimming.
Create Call › Request Body
taskphone^\+[1-9][0-9]{7,14}$ · requiredRequired closed flat JSON Schema using the same calle.result.scalar-object.v1 profile as Goal. At most 32 string, boolean, integer or number properties; additionalProperties must be false. Nested objects, arrays, null values and schema combinators are unsupported.
CALL-E supports a subset of JSON Schema. Property keywords maxLength, minLength, minimum, maximum, and pattern are rejected with HTTP 400 result_schema_invalid before a Call is created.
Use description to guide extraction and enum to list allowed values. Descriptions do not enforce length, range, or pattern constraints; check those business constraints in your application. See Result schema for a supported example and schema errors for corrections.
Optional destination region. Inferred from the phone when omitted. An explicit region conflicting with the phone requires corrected input.
Optional spoken BCP-47 locale. Inferred from task intent and available regional languages when omitted.
Create Call › Responses
Task prepared and Call durably accepted, or an exact replay returning the same Call ID and current saved state. No duplicate dialing on replay.
idAPI Call resource ID. Use this ID for API paths and event correlation, not the telephone ID in Billing.
call_idTelephone call ID shown in Billing, using the same identity as Goal Run call_id. Always present; null until recorded, including cancellation before dialing. Independent of business result availability. Does not indicate whether charges have settled. Use id, not this field, for API paths.
objectstatusStable execution state. No-answer, busy and declined calls complete execution normally. Technical execution failures are failed; explicit cancellation is canceled. Completed execution may still have result_status=pending while its business result is being processed.
call_outcomeReported telephone outcome, separate from business success and billing connection evidence. Null before a telephone outcome is known or when execution is canceled or fails technically.
result_statusPending means keep polling. Available includes an empty result object. Unavailable means no schema-valid business result could be produced; inspect error for technical failures. Not applicable is used for cancellation and technical execution failure.
Recorded conversation turns in order, independent of the business result. Always present; empty before terminal execution or when no transcript is available. Never generated from result_schema.
taskphoneregionlocaleResult validated against result_schema and durably persisted. Null while pending, unavailable, not applicable, or on a technical error. Explicit schema-valid task fallbacks are preserved.
Technical execution or result-processing error, or null. No-answer, busy, declined, cancellation and insufficient business evidence do not populate error.
created_atcompleted_atUTC telephone-execution completion time, or null while execution is non-terminal.
Get Call
Polling reads persisted state and never performs extraction or initiates a call.
path Parameters
call_idDeveloper Call id returned by v2.
Get Call › Responses
Committed response.
idAPI Call resource ID. Use this ID for API paths and event correlation, not the telephone ID in Billing.
call_idTelephone call ID shown in Billing, using the same identity as Goal Run call_id. Always present; null until recorded, including cancellation before dialing. Independent of business result availability. Does not indicate whether charges have settled. Use id, not this field, for API paths.
objectstatusStable execution state. No-answer, busy and declined calls complete execution normally. Technical execution failures are failed; explicit cancellation is canceled. Completed execution may still have result_status=pending while its business result is being processed.
call_outcomeReported telephone outcome, separate from business success and billing connection evidence. Null before a telephone outcome is known or when execution is canceled or fails technically.
result_statusPending means keep polling. Available includes an empty result object. Unavailable means no schema-valid business result could be produced; inspect error for technical failures. Not applicable is used for cancellation and technical execution failure.
Recorded conversation turns in order, independent of the business result. Always present; empty before terminal execution or when no transcript is available. Never generated from result_schema.
taskphoneregionlocaleResult validated against result_schema and durably persisted. Null while pending, unavailable, not applicable, or on a technical error. Explicit schema-valid task fallbacks are preserved.
Technical execution or result-processing error, or null. No-answer, busy, declined, cancellation and insufficient business evidence do not populate error.
created_atcompleted_atUTC telephone-execution completion time, or null while execution is non-terminal.
Cancel Call
Cancellation is idempotent for terminal calls. Once provider submission starts, returns 409 call_cannot_cancel; it does not hang up an active call.
path Parameters
call_idDeveloper Call id returned by v2.
Cancel Call › Responses
Committed response.
idAPI Call resource ID. Use this ID for API paths and event correlation, not the telephone ID in Billing.
call_idTelephone call ID shown in Billing, using the same identity as Goal Run call_id. Always present; null until recorded, including cancellation before dialing. Independent of business result availability. Does not indicate whether charges have settled. Use id, not this field, for API paths.
objectstatusStable execution state. No-answer, busy and declined calls complete execution normally. Technical execution failures are failed; explicit cancellation is canceled. Completed execution may still have result_status=pending while its business result is being processed.
call_outcomeReported telephone outcome, separate from business success and billing connection evidence. Null before a telephone outcome is known or when execution is canceled or fails technically.
result_statusPending means keep polling. Available includes an empty result object. Unavailable means no schema-valid business result could be produced; inspect error for technical failures. Not applicable is used for cancellation and technical execution failure.
Recorded conversation turns in order, independent of the business result. Always present; empty before terminal execution or when no transcript is available. Never generated from result_schema.
taskphoneregionlocaleResult validated against result_schema and durably persisted. Null while pending, unavailable, not applicable, or on a technical error. Explicit schema-valid task fallbacks are preserved.
Technical execution or result-processing error, or null. No-answer, busy, declined, cancellation and insufficient business evidence do not populate error.
created_atcompleted_atUTC telephone-execution completion time, or null while execution is non-terminal.
List Events
Poll durable JSON event pages, not SSE. Events include call.accepted, call.in_progress, call.ringing, call.connected, call.asr, call.speech, call.interrupted, call.dtmf, call.ended, call.result_ready, and call.completed/failed/canceled. Not every call emits every event type. Speech details preserve observed text, speaker, turn and optional occurred_at. ASR may contain partial fragments or revised hypotheses; no is_final flag or final-sentence guarantee is provided. Do not concatenate every update into a transcript. Deduplicate by event ID, not turn or text. Persistence order includes late arrivals; IDs remain stable. Follow next_cursor for additional available pages. Retain the last event ID for later polls even when next_cursor is null, and keep it on empty pages. Empty pages do not mean completion. Existing lifecycle cursors remain valid. Invalid or foreign cursors return 400 invalid_request. Reads do not dial, infer or persist anything.
path Parameters
call_idDeveloper Call id returned by v2.
query Parameters
cursorOpaque next_cursor or last returned event ID; scoped to this call. Retain the saved cursor on an empty page.
limitPage size, 1-100. Invalid or out-of-range values return 400 invalid_request.
List Events › Responses
Committed response.
objectAlways list for paginated list responses.
Events in this page, ordered from oldest to newest for the requested cursor window.
next_cursorCursor for the next page. null means there are no more events.