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 aliases (page, page_size).
path Parameters
AccountSid^AC[0-9a-f]{32}$ · requiredYour Voice Account SID. It must equal the Basic authentication username.
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 when there are no more results.
previous_page_uriPath of the previous page. Omitted 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. The request body may be at most 1 MiB.
path Parameters
AccountSid^AC[0-9a-f]{32}$ · requiredYour Voice Account SID. It must equal the Basic authentication username.
Create a call › Request Body
To^\+?[0-9]{7,15}$ · requiredDestination phone number. E.164 format, or 7 to 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 your Signals project owns; 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. 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 to 600 are clamped rather than rejected.
CallerId^\+?[0-9]{7,15}$Overrides the caller ID presented on this call. Must be a phone number your project owns (error 21210) and in the same format as To and 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. Providing ApplicationSid always fails the request with error 21605; use Url or Twiml instead. A Signals voice application ID is not accepted here either.
Create a call › Responses
Call created.
sidUnique identifier of this call.
account_sidSID of the Voice Account that owns this call.
api_versiondate_createdRFC 2822 formatted creation timestamp.
date_updatedRFC 2822 formatted last-update timestamp.
annotationReserved. Always null.
answered_byReserved for answering-machine detection. Always null.
caller_nameReserved for caller name lookup. Always null.
directionCall direction, for example inbound, outbound-api or outbound-dial.
durationCall duration in seconds. Null until the call has ended and been recorded.
end_timeRFC 2822 formatted end timestamp. Null until the call ends.
forwarded_fromReserved. Always null.
fromfrom_formattedIdentical to from.
group_sidReserved. Always null.
trunk_sidReserved. Always null.
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 number used for this call, when known.
pricePrice field reported by the voice engine. Signals charges for the call appear in Signals usage, not in this field.
price_unitCurrency of price.
start_timeRFC 2822 formatted answer timestamp. Null until the call is answered.
statusCurrent call status.
Paths of resources related to this call.
toto_formattedIdentical to to.
uriPath of this call resource.
Fetch a call
Returns the current state of a single call. The .json suffix is optional.
path Parameters
AccountSid^AC[0-9a-f]{32}$ · requiredYour Voice Account SID. It must equal the Basic authentication username.
CallSid^CA[0-9a-f]{32}$ · requiredSID of the call. Lowercase hexadecimal only; any other form returns 404.
Fetch a call › Responses
Call details.
sidUnique identifier of this call.
account_sidSID of the Voice Account that owns this call.
api_versiondate_createdRFC 2822 formatted creation timestamp.
date_updatedRFC 2822 formatted last-update timestamp.
annotationReserved. Always null.
answered_byReserved for answering-machine detection. Always null.
caller_nameReserved for caller name lookup. Always null.
directionCall direction, for example inbound, outbound-api or outbound-dial.
durationCall duration in seconds. Null until the call has ended and been recorded.
end_timeRFC 2822 formatted end timestamp. Null until the call ends.
forwarded_fromReserved. Always null.
fromfrom_formattedIdentical to from.
group_sidReserved. Always null.
trunk_sidReserved. Always null.
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 number used for this call, when known.
pricePrice field reported by the voice engine. Signals charges for the call appear in Signals usage, not in this field.
price_unitCurrency of price.
start_timeRFC 2822 formatted answer timestamp. Null until the call is answered.
statusCurrent call status.
Paths of resources related to this call.
toto_formattedIdentical to to.
uriPath of this call resource.
Update a live call
Send form fields to redirect or end a call. Use exactly one of Url, Twiml, or Status. Method applies only to Url and defaults to POST. Status=completed ends an in-progress call; Status=canceled cancels a call before answer. A successful command response can still show the current non-terminal status until the switch confirms termination. POST returns the call resource; PATCH is not accepted. Existing JSON update clients must adopt this form contract.
path Parameters
AccountSid^AC[0-9a-f]{32}$ · requiredYour Voice Account SID. It must equal the Basic authentication username.
CallSid^CA[0-9a-f]{32}$ · requiredSID of the call. Lowercase hexadecimal only; any other form returns 404.
Update a live call › Request Body
UrlAbsolute HTTP or HTTPS OneML URL for an in-progress call.
MethodTwimlInline OneML for an in-progress call.
Statuscompleted ends an in-progress call; canceled requires a call that has not answered.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: Url | |
| type = object · requires: Twiml | |
| type = object · requires: Status |
UrlAbsolute HTTP or HTTPS OneML URL for an in-progress call.
MethodTwimlInline OneML for an in-progress call.
Statuscompleted ends an in-progress call; canceled requires a call that has not answered.
Update a live call › Responses
The update was accepted. Switch execution is asynchronous.
sidUnique identifier of this call.
account_sidSID of the Voice Account that owns this call.
api_versiondate_createdRFC 2822 formatted creation timestamp.
date_updatedRFC 2822 formatted last-update timestamp.
annotationReserved. Always null.
answered_byReserved for answering-machine detection. Always null.
caller_nameReserved for caller name lookup. Always null.
directionCall direction, for example inbound, outbound-api or outbound-dial.
durationCall duration in seconds. Null until the call has ended and been recorded.
end_timeRFC 2822 formatted end timestamp. Null until the call ends.
forwarded_fromReserved. Always null.
fromfrom_formattedIdentical to from.
group_sidReserved. Always null.
trunk_sidReserved. Always null.
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 number used for this call, when known.
pricePrice field reported by the voice engine. Signals charges for the call appear in Signals usage, not in this field.
price_unitCurrency of price.
start_timeRFC 2822 formatted answer timestamp. Null until the call is answered.
statusCurrent call status.
Paths of resources related to this call.
toto_formattedIdentical to to.
uriPath of this call resource.
End a call
Requests hang-up of an active call, or cancellation before answer. A queued call can be canceled before origination.
path Parameters
AccountSid^AC[0-9a-f]{32}$ · requiredYour Voice Account SID. It must equal the Basic authentication username.
CallSid^CA[0-9a-f]{32}$ · requiredSID of the call. Lowercase hexadecimal only; any other form returns 404.
End a call › Responses
The command was accepted. The response has no body; native events confirm the final status.