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

Name	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

Name	Type	Description
`answer_method`	string	HTTP verb for answer_url. Default is POST.
`ring_url`	string	Optional URL notified when the call starts ringing.
`ring_method`	string	HTTP verb for ring_url. Default is POST.
`hangup_url`	string	Optional URL notified when the call is hung up.
`hangup_method`	string	HTTP verb for hangup_url. Default is POST.
`fallback_url`	string	Invoked if answer_url fails after 3 retries or 60s timeout.
`fallback_method`	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

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

Advanced Parameters

Request Parameters

Name	Type	Description
`caller_name`	string	Sets caller name (up to 50 characters). Defaults to caller's name.
`send_digits`	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`	boolean	If true, sends send_digits during pre-answer. Default: false.
`time_limit`	integer	Max duration of call in seconds (after answered). Default: 14400 (4 hours). Calls ≥ 86400s are disconnected at 24h.
`hangup_on_ring`	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",
  "call_uuid": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f"
}

Note: The call_uuid is the unique identifier for the call.

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

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

Parameters Sent to answer_url and fallback_url

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

Parameters Sent to hangup_url

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

Call Management

Machine Detection

Make an Outbound Call

Required Parameters

Request Parameters

Callback Parameters

Request Parameters

Machine Detection Parameters

Request Parameters

Advanced Parameters

Request Parameters

Request Example

Response Example

Parameters Sent to Callback URLs

Parameters Sent to ring_url

Parameters Sent to answer_url and fallback_url

Parameters Sent to hangup_url

On this page