Skip to main content
POST
Create Call
Billable - retry unsafe
Recommended. This endpoint is part of the public /v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.
Initiates a single outbound call to the specified phone number using the given agent. The call starts as soon as the recipient answers.

When to use this

Use this when you need to make a single, immediate call, for example when triggering a follow-up after a form submission, sending a verification call, or making a click-to-call request from your CRM.
This operation can place a real, billable call. It is not safe to retry blindly after a timeout. Reconcile recent calls using stable metadata before submitting another request.

Destination validation

phone_number must be a valid international phone number in E.164 format (including the country code). For non-SIP routes, the destination country and prefix must also be enabled in Workspace Settings > Telephony Config before the call is created. Invalid phone number formats return 400 Bad Request. Unsupported countries, unsupported prefixes, and workspaces with no enabled destination countries return 403 Forbidden.

Dynamic variables

Pass a metadata object to inject context into the agent’s prompt at call time. Reference these values in the prompt using {{variable_name}}:
In your prompt, you can then write: “Hi , calling to confirm your appointment.”

Verify the result

Store the returned id immediately. Fetch it with Get Call Details or process terminal events through Webhooks. A successful create response means the call was accepted for scheduling, not that the recipient answered.

Errors and recovery

  • 400 Bad Request: fix the E.164 number, missing metadata, or another invalid field.
  • 402 Payment Required: add wallet balance before creating another call.
  • 403 Forbidden: verify KYC, workspace access, and Telephony Config coverage.
  • 404 Not Found: verify the signed agent ID and published version.
  • Network timeout or transient 5xx: list recent calls and match your metadata before retrying.

Authorizations

Authorization
string
header
required

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

Body

application/json
phone_number
string
required

Phone number to call (must include country code). Format: +[country code][phone number]

Example:

"+911234567890"

agent_id
string
required

Agent ID to use for the call. Must belong to the authenticated organization.

Example:

"mgao6051Rk718Y"

metadata
object
required

Metadata for the call including customer information and any additional context. This data will be available during the call for personalization.

Example:
agent_version_number
number

Specific agent version number to use (optional). If provided, must be a published version. If not provided, will use the latest published version.

Example:

2

notes
object

Optional notes stored on the call log. Must be a JSON object with at most 15 top-level keys.

Example:

Response

Call created and queued successfully.

id
string
required

Unique call ID for tracking. Use this ID to reference the call in other API endpoints.

Example:

"call_mfgsn90vwcozgb"

to_phone_number
string
required

The phone number that will receive the call.

Example:

"+911234567890"

agent_id
string
required

The ID of the agent used for this call.

Example:

"agent_mfgsn90vwcozgb"

agent_version_number
number

The version number of the agent used for this call.

Example:

2