Create, list, fetch, update, and end voice calls.
List calls
Returns a page of calls for the account, most recent first. Pagination accepts either the PascalCase query parameters below or their lowercase/snake_case aliases (page, page_size).
path Parameters
AccountSidSID of the account that owns the calls.
query Parameters
PageZero-indexed page number.
PageSizeNumber of calls per page.
List calls › Responses
Call list.
uriPath of this request, without query parameters.
pageCurrent page number.
page_sizeCalls per page.
first_page_uriPath of the first page.
next_page_uriPath of the next page. Omitted from the response when there are no more results.
previous_page_uriPath of the previous page. Omitted from the response on the first page.
Create a call
Originates an outbound call. The request body is form-encoded (application/x-www-form-urlencoded) with PascalCase field names, not JSON. Provide Url or Twiml so the call has a OneML document to run once it connects; if both are present, Url is used and Twiml is ignored.
path Parameters
AccountSidSID of the account that owns the calls.
Create a call › Request Body
To^\+?[0-9]{7,15}$ · requiredDestination phone number. E.164 format, or 7-15 digits with an optional leading plus sign.
From^\+?[0-9]{7,15}$ · requiredCaller ID to originate the call from. Must be a phone number owned by the account; an unowned number returns error 21210.
UrlAbsolute http(s) URL fetched for a OneML document once the call connects. Required unless Twiml is given. If both Url and Twiml are present, Url is used and Twiml is ignored.
TwimlInline OneML document to run instead of fetching Url. Ignored if Url is also present. Must parse as valid OneML, or the request fails with error 12100.
MethodHTTP method used to fetch Url. Any value other than GET is treated as POST.
StatusCallbackAbsolute http(s) URL notified about call status changes.
StatusCallbackMethodHTTP method used to call StatusCallback. Any value other than GET is treated as POST.
StatusCallbackEventCall lifecycle events that trigger StatusCallback. Repeat the parameter to request more than one event. Defaults to ["completed"] when omitted or empty. This list reflects the events the platform emits; other values are accepted but never match an emitted event.
TimeoutSeconds to let the destination ring before the call is treated as unanswered. Values outside 1-600 are clamped rather than rejected.
CallerId^\+?[0-9]{7,15}$Overrides the caller ID presented on this call. Must be a phone number owned by the account (error 21210) and in the same format as To/From (error 13214).
TimeLimitMaximum call duration in seconds, measured from answer.
SendDigits^[0-9A-Da-d#*wW]{0,3…DTMF digits to play after the call connects. At most 32 characters from 0-9, A-D, a-d, #, *, w, and W (w inserts a 0.5 second pause).
ApplicationSidNot supported by this API. Providing ApplicationSid always fails the request with error 21605; use Url or Twiml instead.
Create a call › Responses
Call created.
sidUnique identifier of this call.
account_sidSID of the account that owns this call.
api_versiondate_createdRFC 2822 formatted creation timestamp.
date_updatedRFC 2822 formatted last-update timestamp.
annotationReserved for future use. Always null in the current implementation.
answered_byReserved for future use (answering-machine detection). Always null in the current implementation.
caller_nameReserved for future use (CNAM lookup). Always null in the current implementation.
directionCall direction, for example inbound, outbound-api, or outbound-dial.
durationBilled call duration in seconds. Null until the call has an associated CDR.
end_timeRFC 2822 formatted end timestamp. Null until the call ends.
forwarded_fromReserved for future use. Always null in the current implementation.
fromfrom_formattedCurrently always identical to from.
group_sidReserved for future use. Always null in the current implementation.
trunk_sidReserved for future use; this system does not model trunk SIDs. Always null in the current implementation.
parent_call_sidSID of the call that created this one, when applicable.
queue_timeMilliseconds the call waited between being queued and initiated. "0" when not applicable.
phone_number_sidSID of the DID used for this call, when known.
priceCost of the call, negative for a debit. Null until the call is priced.
price_unitCurrency of price.
start_timeRFC 2822 formatted answer timestamp. Null until the call is answered.
statusCurrent call status.
URIs of resources related to this call.
toto_formattedCurrently always identical to to.
uriPath of this call resource.
Fetch a call
Returns the current state of a single call.
path Parameters
AccountSidSID of the account that owns the call.
CallSidSID of the call. The .json suffix is optional.
Fetch a call › Responses
Call details.
sidUnique identifier of this call.
account_sidSID of the account that owns this call.
api_versiondate_createdRFC 2822 formatted creation timestamp.
date_updatedRFC 2822 formatted last-update timestamp.
annotationReserved for future use. Always null in the current implementation.
answered_byReserved for future use (answering-machine detection). Always null in the current implementation.
caller_nameReserved for future use (CNAM lookup). Always null in the current implementation.
directionCall direction, for example inbound, outbound-api, or outbound-dial.
durationBilled call duration in seconds. Null until the call has an associated CDR.
end_timeRFC 2822 formatted end timestamp. Null until the call ends.
forwarded_fromReserved for future use. Always null in the current implementation.
fromfrom_formattedCurrently always identical to from.
group_sidReserved for future use. Always null in the current implementation.
trunk_sidReserved for future use; this system does not model trunk SIDs. Always null in the current implementation.
parent_call_sidSID of the call that created this one, when applicable.
queue_timeMilliseconds the call waited between being queued and initiated. "0" when not applicable.
phone_number_sidSID of the DID used for this call, when known.
priceCost of the call, negative for a debit. Null until the call is priced.
price_unitCurrency of price.
start_timeRFC 2822 formatted answer timestamp. Null until the call is answered.
statusCurrent call status.
URIs of resources related to this call.
toto_formattedCurrently always identical to to.
uriPath of this call resource.
Update a live call
Redirects a live call to a new OneML source. Unlike the rest of this API, the request body is JSON with snake_case fields, not form-encoded PascalCase. PATCH is also accepted on this path and behaves identically to POST. All fields are optional; only the ones provided are applied.
path Parameters
AccountSidSID of the account that owns the call.
CallSidSID of the call. The .json suffix is optional.
Update a live call › Request Body
voice_urlNew OneML webhook URL to redirect the live call to.
voice_methodHTTP method used to fetch voice_url.
twimlInline OneML document to run instead of fetching voice_url.
Update a live call › Responses
The call was redirected. The response has no body.
End a call
Hangs up a live call immediately.
path Parameters
AccountSidSID of the account that owns the call.
CallSidSID of the call. The .json suffix is optional.
End a call › Responses
The call was ended. The response has no body.