Sign in

v3

latestOpenAPI 3.1.02026-08-087684214.2 KB
calls

Create Outbound Call

Initiate an outbound call.

This endpoint allows you to programmatically make phone calls from your agent to any phone number. Use fromNumberId to pick which of the agent's numbers to use as caller ID; if omitted, the first assigned number is used.

Flow:

  1. Validates the agent belongs to your account and has a phone number
  2. Initiates a call from the agent's number to the destination
  3. When recipient answers, speaks the initial greeting (if provided)
  4. Listens for recipient's speech and sends to your webhook
  5. Continues conversation using your webhook responses
post/v1/calls

Request body

agentIdstring required

Agent ID to make the call from

toNumberstring required

Phone number to call (E.164 format)

fromNumberIdstring nullable

Optional phone number ID to use as caller ID. Must belong to the agent. If omitted, the agent's first assigned number is used.

initialGreetingstring nullable

Optional initial greeting to speak when recipient answers

voicestring nullable

Voice ID override for this call (uses agent's configured voice if omitted)

systemPromptstring nullable

When provided, uses a built-in LLM for the conversation instead of forwarding to a webhook. The prompt defines the AI's personality and conversation topic.

modelTier'turbo' | 'balanced' | 'max' nullable

Optional model tier override for this call's built-in conversation. Only applies when systemPrompt is provided; defaults to the agent's configured modelTier.

variablesobject nullable

Optional per-call dynamic variables. Values are substituted into {{var_name}} placeholders in the agent's system prompt and initial greeting at call time. Requires either systemPrompt or a hosted-mode agent.

callScreeningIdentitystring nullable

For outbound calls that hit an automated call screener (e.g. iOS 26 Call Screening or Android Call Screen): the identity the agent gives when asked who is calling. Overrides the agent's stored default for this call. Both identity and purpose are required to enable screening; if only a purpose is set, the agent's name is used.

callScreeningPurposestring nullable

For outbound calls that hit an automated call screener: the purpose the agent gives when asked why it is calling. Overrides the agent's stored default for this call.

Response

Successful Response

{"stackTrail":"paths:/v1/calls:post:responses:200:content:application/json:schema","oasType":"schema","type":"unknown"}