Create Call
Create a single outbound call.
/v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.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.
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"
The version number of the agent used for this call.
2