Create Phone Call
Initiates an outbound call with the specified agent, caller, and destination numbers. Supports dynamic variables for personalization. Returns the created call record, including the callId for future retrieval or cancellation.
Authorizations
Authenticate every request by passing your API key in the X-API-Key header. To get your key, go to Dashboard → API Keys and create or copy your Production API key.
Body
Request body to initiate a single outbound call. Requires a SigmaMind-provisioned caller number, a destination number, and the agent that will handle the call. Dynamic variables allow the agent to personalise the conversation at runtime.
Caller's phone number in +E.164 format (e.g., +14155552671). Must be a number provisioned in SigmaMind or configured via SIP trunking that is enabled for outbound calls. This number appears as the caller ID on the recipient's device.
^\+[1-9][0-9]{6,14}$"+14155552671"
Destination phone number to dial, in +E.164 format (e.g., +14155552671). Must be a valid number capable of receiving calls. Include the country code — local-format numbers without a leading '+' are rejected.
^\+[1-9][0-9]{6,14}$"+14155552671"
Unique identifier of the agent that will handle this call. The agent controls the conversation flow, prompts, and any tools invoked during the call. If omitted, the default agent configured for the caller's phone number is used.
64"D5D0p7TUs66TTAEAx"
Key-value pairs used to personalise the agent's behaviour for this specific call. Keys must match the variable names defined in the agent's configuration (e.g., 'customer_name', 'account_id'). These values are injected into the agent's prompts and tools at call start. Leave empty if the agent requires no personalisation.
{
"customer_name": "Michael",
"account_id": "ACC-001"
}Response
Created
Full details of a single call record. Includes call identity, direction, status, timing, the agent that handled it, and the campaign it belongs to if applicable.
Unique identifier for this call. Use this value as callId when retrieving, updating, or referencing this call in subsequent API calls.
"call_AuUKK371Spr5nHJS"
Direction and channel of the call. 'inbound' means the call was received by SigmaMind from an external caller. 'outbound' means SigmaMind dialled the destination number. 'web' means the call originated from a browser-based session.
inbound, outbound, web, chat "outbound"
Caller phone number used to dial contacts in this campaign. This number appears as the caller ID on recipients' devices.
Full details of a campaign record. Includes the campaign's identity, current status, schedule configuration, the agent handling calls, and the caller phone number used to dial contacts.
Current lifecycle state of the call. 'scheduled' means the call is queued but dialling has not started. 'in_progress' means the call is currently active. 'ended' means the call completed normally. 'not_connected' means the call was attempted but the recipient did not answer or connect. 'error' means the system encountered a failure while trying to place or manage the call.
scheduled, in_progress, ended, not_connected, error "ended"
transcript of the conversation in chat
UTC timestamp when the call was connected and the active session began, in ISO 8601 format. Null if the call never reached in_progress state.
"2024-04-20T10:00:00.000Z"
UTC timestamp when the call session ended, in ISO 8601 format. Null if the call is still in progress or was never connected.
"2024-04-20T10:02:00.000Z"
Total duration of the connected call session in seconds. Measured from startTime to endTime. Null if the call was never connected.
120
Reason the call session ended. 'silence_timed_out' — call ended due to configured silence timeout. 'agent_ended_call' — the AI agent closed the session. 'user_ended_call' — the recipient hung up the call. 'voicemail_detected' — voicemail was detected during the call. 'ivr_detected' — IVR system was detected during the call. 'agent_transferred_call' — the AI agent transferred the call. 'max_call_duration_exceeded' — maximum call duration limit was exceeded. 'dial_telephony_permission_denied' — outbound dialing permission was denied by telephony provider. 'dial_invalid_destination' — destination number was invalid. 'dial_no_answer' — the call rang but was not answered. 'dial_user_declined' — recipient declined the incoming call. 'dial_busy' — the destination number was busy. 'dial_failed' — outbound dialing failed due to SIP or telephony error. 'error_credit_limit_reached' — insufficient credit balance. 'error_llm' — language model failed to generate a response. 'error_tts' — text-to-speech service error occurred. 'error_asr' — speech recognition service error occurred. 'error_sigmamind' — internal SigmaMind processing error occurred. 'error_telephony' — telephony provider or connection error occurred. 'error_unknown' — unknown internal error occurred. Null if the call has not yet ended.
silence_timed_out, agent_ended_call, user_ended_call, voicemail_detected, ivr_detected, agent_transferred_call, max_call_duration_exceeded, dial_telephony_permission_denied, dial_invalid_destination, dial_no_answer, dial_user_declined, dial_busy, dial_failed, error_credit_limit_reached, error_llm, error_tts, error_asr, error_sigmamind, error_telephony, error_unknown "user_ended_call"
UTC timestamp when this call record was created in the system, in ISO 8601 format. For outbound calls this is typically when the call was scheduled or triggered.
"2024-04-20T09:59:50.000Z"
UTC timestamp when this call record was last updated, in ISO 8601 format. Updates occur when the call status changes, the session ends, or metadata is modified.
"2024-04-20T10:02:05.000Z"
Dynamic key-value pairs that were passed to the agent at call start for personalisation. Keys correspond to variable names defined in the agent's configuration (e.g., 'customer_name', 'account_id'). Null or empty if no dynamic variables were provided when the call was created.
{
"customer_name": "Michael",
"account_id": "ACC-001"
}URL of the call recording audio file. Available after the call ends and recording processing is complete. Null if recording is not enabled for this call or if the call did not connect.
"https://livekitmedia.blob.core.windows.net/recording-container-prod/room-ST_abc123/recording.mp3"
Agent assigned to handle all calls in this campaign. Contains the agent's ID, name, and current status. All contacts in the campaign's contact list will be called using this agent.