For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomeGet API key
DocumentationIntegrationsAPI Reference
DocumentationIntegrationsAPI Reference
  • API Reference
      • GETList Calls
      • POSTCreate Outbound Call
      • POSTCreate Web Call
      • GETGet Call
      • POSTEnd Call
      • GETGet Call Recording
      • GETGet Call Transcript
      • GETStream Call Transcript
      • GETList Calls For Number
LogoLogo
HomeGet API key
API Referencecalls

Create Outbound Call

POST
https://api.agentphone.ai/v1/calls
POST
/v1/calls
1const url = 'https://api.agentphone.ai/v1/calls';
2const options = {
3  method: 'POST',
4  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5  body: '{"agentId":"string","toNumber":"string"}'
6};
7
8try {
9  const response = await fetch(url, options);
10  const data = await response.json();
11  console.log(data);
12} catch (error) {
13  console.error(error);
14}
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
Was this page helpful?
Previous

Create Web Call

Next
Built with

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.

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.

Response

Successful Response

Errors

422
Unprocessable Entity Error