Create Call
Create a single outbound call.
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.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 ametadata object to inject context into the agent’s prompt at call time. Reference these values in the prompt using {{variable_name}}:
Verify the result
Store the returnedid 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.
Verify The Resolved Agent Version
Omitagent_version_number to use the latest published version. The response’s numeric agent_version_number reports the version actually selected for the call. Do not subtract one from a draft version to guess the published version. Record the returned call ID and version, then inspect Get Call Details before retrying an uncertain request.
Errors and recovery
400 Bad Request: fix the E.164 number, missingmetadata, 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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Phone number to call (must include country code). Format: +[country code][phone number]
"+911234567890"
Agent ID to use for the call. Must belong to the authenticated organization.
"mgao6051Rk718Y"
Metadata for the call including customer information and any additional context. This data will be available during the call for personalization.
Specific agent version number to use (optional). If provided, must be a published version. If not provided, will use the latest published version.
2
Optional notes stored on the call log. Must be a JSON object with at most 15 top-level keys.
Response
Call created and queued successfully.
Unique call ID for tracking. Use this ID to reference the call in other API endpoints.
"call_mfgsn90vwcozgb"
The phone number that will receive the call.
"+911234567890"
The ID of the agent used for this call.
"agent_mfgsn90vwcozgb"
Numeric agent version actually selected for this call. If omitted in the request, the latest published version is selected.
2