Skip to main content
POST

Overview

Places a phone call toward your objective. The result has the transcript, a summary, the outcome and a recording link. On a call it:
  • Leaves a short message when it reaches voicemail.
  • Presses keys at a phone menu, or asks for a person.
  • Waits quietly on hold. A long silence ends the call.

Authentication

Requires x402 payment. The first call returns a quote (402). The second call, with payment, places the call.

Request Body

string
What the call should accomplish. 10 to 5,000 characters.
string
Alias for objective. 10 to 5,000 characters.
Quote requests must provide at least one of objective or raw_objective. Paid retries may omit both; they use the stored quote’s objective. Aliases resolve before validation, staging allowance reservation, and moderation. If both are supplied, they must be identical strings. Non-string or conflicting aliases return 400 before reservation or calling, including on paid retries. The resolved objective is moderated before quote preparation.
string | string[]
required
Number(s) in E.164 format, such as +14155551234. Up to 5 numbers for a conference call.
string
The name the caller gives: the person or business the call is for.
string
Who the caller is and how they speak.
string
Background the caller needs.
number
Longest the call may run, 1 to 30. Default: the quote’s estimated_duration_minutes.

Who the caller says it is

The caller uses caller_name. Without it, the name in caller_persona. Without either, your agent’s name if it reads like a person’s. Otherwise “Janine, an assistant”.

Quote Response (402)

Returns context.quote_id, context.success_criteria, context.estimated_duration_minutes, context.conference_mode and context.total.

Completed Job Result

After payment the call starts (202). Poll /v1/requests/{request_id} for the result. The SDKs wait for it: max_duration_minutes (10 if unset) plus two minutes.
string | null
reached_person, voicemail_left, no_answer, refused, phone_menu_dead_end or wrong_number.
string
pass or fail. A voicemail passes only when the objective allows a message.
string | null
Link to the call recording.
string
The transcript.
string
Short summary.
number
Call length.

Conference Calls

Pass several numbers and an objective about connecting them. Everyone joins one call, which the caller moderates. It uses a shared number, with no phone registration fee.

Errors

content_blocked: the objective breaks the content rules. moderation_unavailable (503): the content moderation provider could not be reached, so no call was placed and a settled payment is returned as credit; retry after Retry-After. emergency_number_blocked: emergency numbers cannot be called. invalid_request: fix the field it names.
See Pricing for costs. When success_evaluation is fail, part of the charge is credited back. credit_issued shows the amount.