Make an Outbound Call

Initiate an outbound call to a PSTN number or a SIP endpoint, and make simultaneous bulk calls.

POSThttps://api.vobiz.ai/api/v1/Account/{auth_id}/Call/

This method lets you initiate an outbound call to a PSTN number or a SIP endpoint, and make simultaneous bulk calls.

Authentication Required:

• X-Auth-ID: Your account ID (e.g., {Auth_ID})
• X-Auth-Token: Your account Auth Token
• Content-Type: application/json

Tip: Use < to separate multiple destinations (max 1000). Example: 14157654321<14153464321<sip:john1234@api.vobiz.ai

Required Parameters

Request Parameters

Parameter	Type	Description
`from`required	string	The caller ID phone number in E.164 format (e.g., 14157654321).
`to`required	string	Destination number(s) or SIP URI(s). Use < to separate multiple destinations (max 1000). Examples: 14157654321, sip:john1234@api.vobiz.ai
`answer_url`required	string	URL called when the call is answered. Must return valid XML.

Callback Parameters

Request Parameters

Parameter	Type	Description
`answer_method`optional	string	HTTP verb for answer_url. Default is POST.
`ring_url`optional	string	Optional URL notified when the call starts ringing.
`ring_method`optional	string	HTTP verb for ring_url. Default is POST.
`hangup_url`optional	string	Optional URL notified when the call is hung up.
`hangup_method`optional	string	HTTP verb for hangup_url. Default is POST.
`fallback_url`optional	string	Invoked if answer_url fails after 3 retries or 60s timeout.
`fallback_method`optional	string	HTTP verb for fallback_url. Default is POST.

Machine Detection Parameters

Note: For detailed machine detection documentation, see the Machine Detection page.

Request Parameters

Parameter	Type	Description
`machine_detection`optional	string	Detect machine on answer. Values: true, hangup.
`machine_detection_time`optional	integer	Time in ms to detect machine. Default: 5000. Allowed: 2000–10000.
`machine_detection_url`optional	string	Callback URL for asynchronous machine detection.
`machine_detection_method`optional	string	HTTP verb for machine_detection_url. Default: POST.
`machine_detection_maximum_speech_length`optional	integer	Max speech duration in ms. Default: 5000. Allowed: 1000–6000.
`machine_detection_initial_silence`optional	integer	Max silence after answer (ms). Default: 4500. Allowed: 2000–10000.
`machine_detection_maximum_words`optional	integer	Max number of sentences. Default: 3. Allowed: 2–10.
`machine_detection_initial_greeting`optional	integer	Max greeting length (ms). Default: 1500. Allowed: 1000–5000.

Advanced Parameters

Request Parameters

Parameter	Type	Description
`caller_name`optional	string	Sets caller name (up to 50 characters). Defaults to caller's name.
`send_digits`optional	string	Sends DTMF digits after call is connected. Use w (0.5s wait) or W (1s wait). Example: 1w2W3 or 123@1000 (1000ms tone).
`send_on_preanswer`optional	boolean	If true, sends send_digits during pre-answer. Default: false.
`time_limit`optional	integer	Max duration of call in seconds (after answered). Default: 14400 (4 hours). Calls ≥ 86400s are disconnected at 24h.
`hangup_on_ring`optional	integer	Max duration (in seconds) from start of ringing to hangup.

Request Example

Request Body

{
  "from": "14155551234",
  "to": "14155555678",
  "answer_url": "https://example.com/answer",
  "answer_method": "POST",
  "ring_timeout": "30",
  "time_limit": "3600",
  "hangup_url": "https://example.com/hangup",
  "hangup_method": "POST",
  "caller_name": "John Doe",
  "machine_detection": "false"
}

cURL Example

curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Call/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "14155551234",
    "to": "14155555678",
    "answer_url": "https://example.com/answer",
    "answer_method": "POST"
  }'

Response Example

Success Response (201 Created)

{
  "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
  "message": "call fired",
  "request_uuid": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f"
}

Note: The call_uuid (also referred to as request_uuid) is the unique identifier for the call. Both are equivalent and can be used interchangeably.

Parameters Sent to Callback URLs

For every voice call you make and receive, the system sends a status update to your configured callback URLs. You can read and store this information for analysis, and change the flow of ongoing calls based on the values received.

Parameters Sent to ring_url

Parameter	Type	Description
`From`optional	string	The from number used as the caller ID to initiate the call.
`To`optional	string	The destination that's called.
`RequestUUID`optional	string	An identifier that can uniquely identify a request.
`ALegRequestUUID`optional	string	Identifies the first leg of the call in case there are multiple legs.
`CallUUID`optional	string	The unique identifier for the call.
`Direction`optional	string	The direction of the call. This will have the value "outbound".
`Event`optional	string	The event that triggered this notification. This will have the value "Ring".
`CallStatus`optional	string	The status of the call. This will have the value "ringing".
`SessionStart`optional	string	A timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
`STIRAttestation`optional	string	Gives details about the attestation assigned to the call by Vobiz.

Parameters Sent to answer_url and fallback_url

Parameter	Type	Description
`From`optional	string	The from number used as the caller ID to initiate the call.
`To`optional	string	The destination that's called.
`CallerName`optional	string	The name of the caller, if the call was made from a SIP endpoint.
`RequestUUID`optional	string	An identifier that can uniquely identify a call.
`ALegRequestUUID`optional	string	Identifies the first leg of the call in case there are multiple legs.
`CallUUID`optional	string	The unique identifier for the call.
`Direction`optional	string	The direction of the call. This will have the value "outbound".
`ALegUUID`optional	string	A unique identifier for the A leg of the call.
`Event`optional	string	The event that triggered this notification. This will have the value "StartApp".
`STIRVerification`optional	string	Attestation details. Possible values: Verified, Not Verified, Not Applicable.
`CallStatus`optional	string	The status of the call. This will have the value "in-progress".
`SessionStart`optional	string	Timestamp when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
`STIRAttestation`optional	string	Details about the attestation assigned to the call by Vobiz.

Parameters Sent to hangup_url

Parameter	Type	Description
`From`optional	string	The from number used as the caller ID to initiate the call.
`To`optional	string	The destination that's called.
`RequestUUID`optional	string	An identifier that can uniquely identify a call.
`ALegRequestUUID`optional	string	Identifies the first leg of the call in case there are multiple legs.
`CallUUID`optional	string	The unique identifier for the call.
`Direction`optional	string	The direction of the call. This will be "outbound".
`ALegUUID`optional	string	A unique identifier for the A leg of the call.
`Event`optional	string	The event that triggered this notification. This will have the value "Hangup".
`stir_verification`optional	string	Attestation details. Possible values: Verified, Not Verified, Not Applicable.
`CallStatus`optional	string	The status of the call. This will have the value "completed".
`StartTime`optional	string	Timestamp when the call was initiated. Timezone: Local. Format: yyyy-MM-dd HH:mm:ss
`AnswerTime`optional	string	Timestamp when the call was answered. Timezone: Local. Format: yyyy-MM-dd HH:mm:ss
`SessionStart`optional	string	Timestamp when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
`EndTime`optional	string	Timestamp when the call ended. Timezone: Local. Format: yyyy-MM-dd HH:mm:ss
`STIRAttestation`optional	string	Details about the attestation assigned to the call by Vobiz.

Call Management

Machine Detection