openapi: 3.0.1
info:
title: Twilio - Accounts A2p Voice API
description: This is the public Twilio REST API.
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio Support
url: https://support.twilio.com
email: support@twilio.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.52.0
servers:
- url: https://accounts.twilio.com
tags:
- name: Voice
paths:
/v1/Voice/Settings:
servers:
- url: https://insights.twilio.com
description: 'TODO: Resource-level docs'
x-twilio:
defaultOutputProperties:
- advanced_features
- voice_trace
pathType: instance
get:
description: Get the Voice Insights Settings.
tags:
- Voice
parameters:
- name: SubaccountSid
in: query
description: The unique SID identifier of the Subaccount.
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/insights.v1.account_settings'
description: OK
security:
- accountSid_authToken: []
operationId: FetchAccountSettings
x-maturity:
- GA
post:
description: Update a specific Voice Insights Setting.
tags:
- Voice
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/insights.v1.account_settings'
description: OK
security:
- accountSid_authToken: []
operationId: UpdateAccountSettings
x-maturity:
- GA
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UpdateAccountSettingsRequest'
/v1/Voice/{CallSid}/Annotation:
servers:
- url: https://insights.twilio.com
description: 'TODO: Resource-level docs'
x-twilio:
defaultOutputProperties:
- call_sid
- account_sid
pathType: instance
parent: /Voice/{Sid}
post:
description: Update an Annotation for a specific Call.
tags:
- Voice
parameters:
- name: CallSid
in: path
description: The unique string that Twilio created to identify this Call resource. It always starts with a CA.
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/insights.v1.call.annotation'
description: OK
security:
- accountSid_authToken: []
operationId: UpdateAnnotation
x-maturity:
- Beta
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UpdateAnnotationRequest'
get:
description: Get the Annotation for a specific Call.
tags:
- Voice
parameters:
- name: CallSid
in: path
description: The unique SID identifier of the Call.
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/insights.v1.call.annotation'
description: OK
security:
- accountSid_authToken: []
operationId: FetchAnnotation
x-maturity:
- Beta
/v1/Voice/{Sid}:
servers:
- url: https://insights.twilio.com
description: 'TODO: Resource-level docs'
x-twilio:
defaultOutputProperties: []
pathType: instance
dependentProperties:
events:
mapping:
call_sid: sid
resource_url: /v1/Voice/{call_sid}/Events
metrics:
mapping:
call_sid: sid
resource_url: /v1/Voice/{call_sid}/Metrics
summary:
mapping:
call_sid: sid
resource_url: /v1None
annotation:
mapping:
call_sid: sid
resource_url: /v1None
mountName: calls
get:
description: ''
tags:
- Voice
parameters:
- name: Sid
in: path
description: ''
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/insights.v1.call'
description: OK
security:
- accountSid_authToken: []
operationId: FetchCall
x-maturity:
- GA
/v1/Voice/Summaries:
servers:
- url: https://insights.twilio.com
description: 'TODO: Resource-level docs'
x-twilio:
defaultOutputProperties:
- account_sid
- call_sid
- create_time
- start_time
- end_time
- duration
- connect_duration
- call_type
- call_state
pathType: list
mountName: call_summaries
className: call_summaries
get:
description: Get a list of Call Summaries.
tags:
- Voice
parameters:
- name: From
in: query
description: A calling party. Could be an E.164 number, a SIP URI, or a Twilio Client registered name.
schema:
type: string
x-twilio:
pii:
handling: standard
deleteSla: 30
- name: To
in: query
description: A called party. Could be an E.164 number, a SIP URI, or a Twilio Client registered name.
schema:
type: string
x-twilio:
pii:
handling: standard
deleteSla: 30
- name: FromCarrier
in: query
description: An origination carrier.
schema:
type: string
- name: ToCarrier
in: query
description: A destination carrier.
schema:
type: string
- name: FromCountryCode
in: query
description: A source country code based on phone number in From.
schema:
type: string
- name: ToCountryCode
in: query
description: A destination country code. Based on phone number in To.
schema:
type: string
- name: Branded
in: query
description: A boolean flag indicating whether or not the calls were branded using Twilio Branded Calls.
schema:
type: boolean
- name: VerifiedCaller
in: query
description: A boolean flag indicating whether or not the caller was verified using SHAKEN/STIR.
schema:
type: boolean
- name: HasTag
in: query
description: A boolean flag indicating the presence of one or more [Voice Insights Call Tags](https://www.twilio.com/docs/voice/voice-insights/api/call/details-call-tags).
schema:
type: boolean
- name: StartTime
in: query
description: A Start time of the calls. xm (x minutes), xh (x hours), xd (x days), 1w, 30m, 3d, 4w or datetime-ISO. Defaults to 4h.
schema:
type: string
- name: EndTime
in: query
description: An End Time of the calls. xm (x minutes), xh (x hours), xd (x days), 1w, 30m, 3d, 4w or datetime-ISO. Defaults to 0m.
schema:
type: string
- name: CallType
in: query
description: A Call Type of the calls. One of `carrier`, `sip`, `trunking` or `client`.
schema:
type: string
- name: CallState
in: query
description: A Call State of the calls. One of `ringing`, `completed`, `busy`, `fail`, `noanswer`, `canceled`, `answered`, `undialed`.
schema:
type: string
- name: Direction
in: query
description: A Direction of the calls. One of `outbound_api`, `outbound_dial`, `inbound`, `trunking_originating`, `trunking_terminating`.
schema:
type: string
- name: ProcessingState
in: query
description: A Processing State of the Call Summaries. One of `completed`, `partial` or `all`.
schema:
type: string
$ref: '#/components/schemas/call_summaries_enum_processing_state_request'
- name: SortBy
in: query
description: A Sort By criterion for the returned list of Call Summaries. One of `start_time` or `end_time`.
schema:
type: string
$ref: '#/components/schemas/call_summaries_enum_sort_by'
- name: Subaccount
in: query
description: A unique SID identifier of a Subaccount.
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
- name: AbnormalSession
in: query
description: A boolean flag indicating an abnormal session where the last SIP response was not 200 OK.
schema:
type: boolean
- name: AnsweredBy
in: query
description: An Answered By value for the calls based on `Answering Machine Detection (AMD)`. One of `unknown`, `machine_start`, `machine_end_beep`, `machine_end_silence`, `machine_end_other`, `human` or `fax`.
schema:
type: string
$ref: '#/components/schemas/call_summaries_enum_answered_by'
- name: AnsweredByAnnotation
in: query
description: Either machine or human.
schema:
type: string
- name: ConnectivityIssueAnnotation
in: query
description: A Connectivity Issue with the calls. One of `no_connectivity_issue`, `invalid_number`, `caller_id`, `dropped_call`, or `number_reachability`.
schema:
type: string
- name: QualityIssueAnnotation
in: query
description: A subjective Quality Issue with the calls. One of `no_quality_issue`, `low_volume`, `choppy_robotic`, `echo`, `dtmf`, `latency`, `owa`, `static_noise`.
schema:
type: string
- name: SpamAnnotation
in: query
description: A boolean flag indicating spam calls.
schema:
type: boolean
- name: CallScoreAnnotation
in: query
description: 'A Call Score of the calls. Use a range of 1-5 to indicate the call experience score, with the following mapping as a reference for the rated call [5: Excellent, 4: Good, 3 : Fair, 2 : Poor, 1: Bad].'
schema:
type: string
- name: PageSize
in: query
description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
schema:
type: integer
minimum: 1
maximum: 1000
- name: Page
in: query
description: The page index. This value is simply for client state.
schema:
type: integer
minimum: 0
- name: PageToken
in: query
description: The page token. This is provided by the API.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListCallSummariesResponse'
description: OK
security:
- accountSid_authToken: []
operationId: ListCallSummaries
x-maturity:
- GA
/v1/Voice/{CallSid}/Events:
servers:
- url: https://insights.twilio.com
description: 'TODO: Resource-level docs'
x-twilio:
defaultOutputProperties:
- timestamp
- call_sid
- account_sid
- edge
- name
pathType: list
parent: /Voice/{Sid}
get:
description: Get a list of Call Insight Events for a Call.
tags:
- Voice
parameters:
- name: CallSid
in: path
description: The unique SID identifier of the Call.
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
required: true
- name: Edge
in: query
description: The Edge of this Event. One of `unknown_edge`, `carrier_edge`, `sip_edge`, `sdk_edge` or `client_edge`.
schema:
type: string
$ref: '#/components/schemas/event_enum_twilio_edge'
- name: PageSize
in: query
description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
schema:
type: integer
minimum: 1
maximum: 1000
- name: Page
in: query
description: The page index. This value is simply for client state.
schema:
type: integer
minimum: 0
- name: PageToken
in: query
description: The page token. This is provided by the API.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListEventResponse'
description: OK
security:
- accountSid_authToken: []
operationId: ListEvent
x-maturity:
- Preview
/v1/Voice/{CallSid}/Metrics:
servers:
- url: https://insights.twilio.com
description: 'TODO: Resource-level docs'
x-twilio:
defaultOutputProperties:
- timestamp
- call_sid
- account_sid
- edge
- direction
pathType: list
parent: /Voice/{Sid}
get:
description: Get a list of Call Metrics for a Call.
tags:
- Voice
parameters:
- name: CallSid
in: path
description: The unique SID identifier of the Call.
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
required: true
- name: Edge
in: query
description: The Edge of this Metric. One of `unknown_edge`, `carrier_edge`, `sip_edge`, `sdk_edge` or `client_edge`.
schema:
type: string
$ref: '#/components/schemas/metric_enum_twilio_edge'
- name: Direction
in: query
description: The Direction of this Metric. One of `unknown`, `inbound`, `outbound` or `both`.
schema:
type: string
$ref: '#/components/schemas/metric_enum_stream_direction'
- name: PageSize
in: query
description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
schema:
type: integer
minimum: 1
maximum: 1000
- name: Page
in: query
description: The page index. This value is simply for client state.
schema:
type: integer
minimum: 0
- name: PageToken
in: query
description: The page token. This is provided by the API.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListMetricResponse'
description: OK
security:
- accountSid_authToken: []
operationId: ListMetric
x-maturity:
- Preview
/v1/Voice/{CallSid}/Summary:
servers:
- url: https://insights.twilio.com
description: 'TODO: Resource-level docs'
x-twilio:
defaultOutputProperties:
- call_type
- call_state
- processing_state
- duration
pathType: instance
parent: /Voice/{Sid}
className: call_summary
get:
description: Get a specific Call Summary.
tags:
- Voice
parameters:
- name: CallSid
in: path
description: The unique SID identifier of the Call.
schema:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
required: true
- name: ProcessingState
in: query
description: The Processing State of this Call Summary. One of `complete`, `partial` or `all`.
schema:
type: string
$ref: '#/components/schemas/summary_enum_processing_state'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/insights.v1.call.summary'
description: OK
security:
- accountSid_authToken: []
operationId: FetchSummary
x-maturity:
- GA
/v2/Voice/Countries:
servers:
- url: https://pricing.twilio.com
description: Voice pricing by country
x-twilio:
defaultOutputProperties:
- country
- price_unit
pathType: list
parent: /Voice
get:
description: ''
tags:
- Voice
parameters:
- name: PageSize
in: query
description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
schema:
type: integer
minimum: 1
maximum: 1000
- name: Page
in: query
description: The page index. This value is simply for client state.
schema:
type: integer
minimum: 0
- name: PageToken
in: query
description: The page token. This is provided by the API.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListVoiceCountryResponse'
description: OK
security:
- accountSid_authToken: []
operationId: ListVoiceCountry
x-maturity:
- GA
/v2/Voice/Countries/{IsoCountry}:
servers:
- url: https://pricing.twilio.com
description: Voice pricing by country
x-twilio:
defaultOutputProperties:
- country
- price_unit
pathType: instance
parent: /Voice
get:
description: Fetch a specific Country.
tags:
- Voice
parameters:
- name: IsoCountry
in: path
description: The [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the origin-based voice pricing information to fetch.
schema:
type: string
format: iso-country-code
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pricing.v2.voice.voice_country-instance'
description: OK
security:
- accountSid_authToken: []
operationId: FetchVoiceCountry
x-maturity:
- GA
/v2/Voice/Numbers/{DestinationNumber}:
servers:
- url: https://pricing.twilio.com
description: Voice pricing for a specific phone number
x-twilio:
defaultOutputProperties:
- country
- inbound_call_price
- price_unit
pathType: instance
parent: /Voice
get:
description: Fetch pricing information for a specific destination and, optionally, origination phone number.
tags:
- Voice
parameters:
- name: DestinationNumber
in: path
description: The destination phone number, in [E.164](https://www.twilio.com/docs/glossary/what-e164) format, for which to fetch the origin-based voice pricing information. E.164 format consists of a + followed by the country code and subscriber number.
schema:
type: string
format: phone-number
required: true
- name: OriginationNumber
in: query
description: The origination phone number, in [E.164](https://www.twilio.com/docs/glossary/what-e164) format, for which to fetch the origin-based voice pricing information. E.164 format consists of a + followed by the country code and subscriber number.
schema:
type: string
format: phone-number
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pricing.v2.voice.voice_number'
description: OK
security:
- accountSid_authToken: []
operationId: FetchVoiceNumber
x-maturity:
- GA
components:
schemas:
insights.v1.call.summary:
type: object
properties:
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
call_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Call.
call_type:
type: string
$ref: '#/components/schemas/summary_enum_call_type'
nullable: true
description: The Call Type of the summarized Call. One of `carrier`, `sip`, `trunking` or `client`.
call_state:
type: string
$ref: '#/components/schemas/summary_enum_call_state'
nullable: true
description: The Call State of the summarized Call. One of `ringing`, `completed`, `busy`, `fail`, `noanswer`, `canceled`, `answered`, `undialed`.
answered_by:
type: string
$ref: '#/components/schemas/summary_enum_answered_by'
nullable: true
description: The Answered By value for the summarized call based on `Answering Machine Detection (AMD)`. One of `unknown`, `machine_start`, `machine_end_beep`, `machine_end_silence`, `machine_end_other`, `human` or `fax`. Refer to [AMD](https://www.twilio.com/docs/voice/answering-machine-detection) for more detail.
processing_state:
type: string
$ref: '#/components/schemas/summary_enum_processing_state'
nullable: true
description: The Processing State of the Call Summary. The Processing State will be `partial` until the assembly of the Call Summary finishes, which occurs approximately 30 minutes after Call end. Then the Processing State changes to `complete`
created_time:
type: string
format: date-time
nullable: true
description: The time at which the Call was created, given in ISO 8601 format. Can be different from `start_time` in the event of queueing due to CPS
start_time:
type: string
format: date-time
nullable: true
description: The time at which the Call was started, given in ISO 8601 format.
end_time:
type: string
format: date-time
nullable: true
description: The time at which the Call was ended, given in ISO 8601 format.
duration:
type: integer
nullable: true
description: Duration between when the call was initiated and the call was ended
connect_duration:
type: integer
nullable: true
description: Duration between when the call was answered and when it ended
from:
nullable: true
description: The calling party.
x-twilio:
pii:
handling: standard
deleteSla: 30
to:
nullable: true
description: The called party.
x-twilio:
pii:
handling: standard
deleteSla: 30
carrier_edge:
nullable: true
description: Contains metrics and properties for the Twilio media gateway of a PSTN call.
client_edge:
nullable: true
description: Contains metrics and properties for the Twilio media gateway of a Client call.
sdk_edge:
nullable: true
description: Contains metrics and properties for the SDK sensor library for Client calls.
sip_edge:
nullable: true
description: Contains metrics and properties for the Twilio media gateway of a SIP Interface or Trunking call.
tags:
type: array
items:
type: string
nullable: true
description: Tags applied to calls by Voice Insights analysis indicating a condition that could result in subjective degradation of the call quality.
url:
type: string
format: uri
nullable: true
description: The URL of this resource.
attributes:
nullable: true
description: Attributes capturing call-flow-specific details.
properties:
nullable: true
description: Contains edge-agnostic call-level details.
trust:
nullable: true
description: Contains trusted communications details including Branded Call and verified caller ID.
annotation:
nullable: true
description: Programmatically labeled annotations for the Call. Developers can update the Call Summary records with Annotation during or after a Call. Annotations can be updated as long as the Call Summary record is addressable via the API.
call_summaries_enum_processing_state_request:
type: string
enum:
- completed
- started
- partial
- all
event_enum_level:
type: string
enum:
- UNKNOWN
- DEBUG
- INFO
- WARNING
- ERROR
call_summaries_enum_sort_by:
type: string
enum:
- start_time
- end_time
insights.v1.call.metric:
type: object
properties:
timestamp:
type: string
nullable: true
description: Timestamp of metric sample. Samples are taken every 10 seconds and contain the metrics for the previous 10 seconds.
call_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Call.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: The unique SID identifier of the Account.
edge:
type: string
$ref: '#/components/schemas/metric_enum_twilio_edge'
nullable: true
description: The Twilio media edge this Metric was captured on. One of `unknown_edge`, `carrier_edge`, `sip_edge`, `sdk_edge` or `client_edge`.
direction:
type: string
$ref: '#/components/schemas/metric_enum_stream_direction'
nullable: true
description: The Direction of the media stream from the perspective of the Twilio media edge. One of `unknown`, `inbound`, `outbound` or `both`.
carrier_edge:
nullable: true
description: Contains metrics and properties for the Twilio media gateway of a PSTN call.
sip_edge:
nullable: true
description: Contains metrics and properties for the Twilio media gateway of a SIP Interface or Trunking call.
sdk_edge:
nullable: true
description: Contains metrics and properties for the SDK sensor library for Client calls.
client_edge:
nullable: true
description: Contains metrics and properties for the Twilio media gateway of a Client call.
summary_enum_processing_state:
type: string
enum:
- complete
- partial
event_enum_twilio_edge:
type: string
enum:
- unknown_edge
- carrier_edge
- sip_edge
- sdk_edge
- client_edge
UpdateAnnotationRequest:
type: object
properties:
AnsweredBy:
type: string
$ref: '#/components/schemas/annotation_enum_answered_by'
description: 'Specify which entity answered the call as determined by Answering Machine Detection. Use this to provide feedback on Answering Machine Detection accuracy. Possible enumerated values, one of: `human`, `machine`. `human` indicates the call was answered by a person. `machine` indicates the call was answered by an answering machine.'
ConnectivityIssue:
type: string
$ref: '#/components/schemas/annotation_enum_connectivity_issue'
description: Specify if the call had any connectivity issues. Possible enumerated values, one of `no_connectivity_issue`, `invalid_number`, `caller_id`, `dropped_call`, or `number_reachability`.
QualityIssues:
type: string
description: Specify if the call had any subjective quality issues. Possible values, one or more of `no_quality_issue`, `low_volume`, `choppy_robotic`, `echo`, `dtmf`, `latency`, `owa`, `static_noise`. Use comma separated values to indicate multiple quality issues for the same call.
Spam:
type: boolean
description: A boolean flag to indicate if the call was a spam call. Use this to provide feedback on whether calls placed from your account were marked as spam, or if inbound calls received by your account were unwanted spam. Use `true` if the call was a spam call.
CallScore:
type: integer
nullable: true
description: 'Specify the call score. This is of type integer. Use a range of 1-5 to indicate the call experience score, with the following mapping as a reference for rating the call [5: Excellent, 4: Good, 3 : Fair, 2 : Poor, 1: Bad].'
Comment:
type: string
description: Specify any comments pertaining to the call. `comment` has a maximum character limit of 100. Twilio does not treat this field as PII, so no PII should be included in the `comment`.
Incident:
type: string
description: Associate this call with an incident or support ticket. The `incident` parameter is of type string with a maximum character limit of 100. Twilio does not treat this field as PII, so no PII should be included in `incident`.
call_summaries_enum_answered_by:
type: string
enum:
- unknown
- machine_start
- machine_end_beep
- machine_end_silence
- machine_end_other
- human
- fax
call_summaries_enum_call_type:
type: string
enum:
- carrier
- sip
- trunking
- client
annotation_enum_answered_by:
type: string
enum:
- unknown_answered_by
- human
- machine
pricing.v2.voice.voice_country:
type: object
properties:
country:
type: string
nullable: true
description: The name of the country.
iso_country:
type: string
format: iso-country-code
nullable: true
description: The [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
url:
type: string
format: uri
nullable: true
description: The absolute URL of the resource.
metric_enum_stream_direction:
type: string
enum:
- unknown
- inbound
- outbound
- both
ListMetricResponse:
type: object
properties:
metrics:
type: array
items:
$ref: '#/components/schemas/insights.v1.call.metric'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
annotation_enum_connectivity_issue:
type: string
enum:
- unknown_connectivity_issue
- no_connectivity_issue
- invalid_number
- caller_id
- dropped_call
- number_reachability
metric_enum_twilio_edge:
type: string
enum:
- unknown_edge
- carrier_edge
- sip_edge
- sdk_edge
- client_edge
pricing.v2.voice.voice_country-instance:
type: object
properties:
country:
type: string
nullable: true
description: The name of the country.
iso_country:
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twilio/refs/heads/main/openapi/twilio-voice-api-openapi.yml