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:

Validates the agent belongs to your account and has a phone number
Initiates a call from the agent’s number to the destination
When recipient answers, speaks the initial greeting (if provided)
Listens for recipient’s speech and sends to your webhook
Continues conversation using your webhook responses

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

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Sub-Account-IdstringOptional

Target a sub-account. Pass a sub-account ID to scope this request. Omit to use the master account.

Request

This endpoint expects an object.

agentIdstringRequired

Agent ID to make the call from

toNumberstringRequired

Phone number to call (E.164 format)

fromNumberIdstring or nullOptional

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 or nullOptional

Optional initial greeting to speak when recipient answers

voicestring or nullOptional

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

systemPromptstring or nullOptional

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.

variablesmap from strings to strings or nullOptional

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 or nullOptional

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 or nullOptional

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

Errors

422

Unprocessable Entity Error

1	import { AgentPhoneClient } from "agentphone";
2
3	async function main() {
4	const client = new AgentPhoneClient({
5	token: "YOUR_TOKEN_HERE",
6	});
7	await client.calls.createOutboundCall({
8	agentId: "string",
9	toNumber: "string",
10	});
11	}
12	main();