openapi: 3.2.0
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:
call_summaries_enum_sort_by:
type: string
enum:
- start_time
- end_time
insights.v1.call.annotation:
type: object
properties:
call_sid:
type:
- string
- 'null'
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
description: The unique SID identifier of the Call.
account_sid:
type:
- string
- 'null'
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
description: The unique SID identifier of the Account.
answered_by:
type:
- string
- 'null'
$ref: '#/components/schemas/annotation_enum_answered_by'
description: 'Specifies which entity answered the call as determined by Answering Machine Detection. 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.'
connectivity_issue:
type:
- string
- 'null'
$ref: '#/components/schemas/annotation_enum_connectivity_issue'
description: Specifies if the call had any connectivity issues. One of `no_connectivity_issue`, `invalid_number`, `caller_id`, `dropped_call`, or `number_reachability`.
quality_issues:
type:
- array
- 'null'
items:
type: string
description: Specifies if the call had any subjective quality issues. Possible values are one or more of `no_quality_issue`, `low_volume`, `choppy_robotic`, `echo`, `dtmf`, `latency`, `owa`, or `static_noise`.
spam:
type:
- boolean
- 'null'
description: 'Specifies 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. Is of type Boolean: true, false. Use true if the call was a spam call.'
call_score:
type:
- integer
- 'null'
description: 'Specifies the Call Score, if available. 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
- 'null'
description: Specifies any comments pertaining to the call. Twilio does not treat this field as PII, so no PII should be included in comments.
incident:
type:
- string
- 'null'
description: Incident or support ticket associated with this call. The `incident` property 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`.
url:
type:
- string
- 'null'
format: uri
annotation_enum_answered_by:
type: string
enum:
- unknown_answered_by
- human
- machine
insights.v1.call.summary:
type: object
properties:
account_sid:
type:
- string
- 'null'
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
description: The unique SID identifier of the Account.
call_sid:
type:
- string
- 'null'
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
description: The unique SID identifier of the Call.
call_type:
type:
- string
- 'null'
$ref: '#/components/schemas/summary_enum_call_type'
description: The Call Type of the summarized Call. One of `carrier`, `sip`, `trunking` or `client`.
call_state:
type:
- string
- 'null'
$ref: '#/components/schemas/summary_enum_call_state'
description: The Call State of the summarized Call. One of `ringing`, `completed`, `busy`, `fail`, `noanswer`, `canceled`, `answered`, `undialed`.
answered_by:
type:
- string
- 'null'
$ref: '#/components/schemas/summary_enum_answered_by'
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
- 'null'
$ref: '#/components/schemas/summary_enum_processing_state'
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
- 'null'
format: date-time
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
- 'null'
format: date-time
description: The time at which the Call was started, given in ISO 8601 format.
end_time:
type:
- string
- 'null'
format: date-time
description: The time at which the Call was ended, given in ISO 8601 format.
duration:
type:
- integer
- 'null'
description: Duration between when the call was initiated and the call was ended
connect_duration:
type:
- integer
- 'null'
description: Duration between when the call was answered and when it ended
from:
description: The calling party.
x-twilio:
pii:
handling: standard
deleteSla: 30
to:
description: The called party.
x-twilio:
pii:
handling: standard
deleteSla: 30
carrier_edge:
description: Contains metrics and properties for the Twilio media gateway of a PSTN call.
client_edge:
description: Contains metrics and properties for the Twilio media gateway of a Client call.
sdk_edge:
description: Contains metrics and properties for the SDK sensor library for Client calls.
sip_edge:
description: Contains metrics and properties for the Twilio media gateway of a SIP Interface or Trunking call.
tags:
type:
- array
- 'null'
items:
type: string
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
- 'null'
format: uri
description: The URL of this resource.
attributes:
description: Attributes capturing call-flow-specific details.
properties:
description: Contains edge-agnostic call-level details.
trust:
description: Contains trusted communications details including Branded Call and verified caller ID.
annotation:
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.
summary_enum_processing_state:
type: string
enum:
- complete
- partial
metric_enum_stream_direction:
type: string
enum:
- unknown
- inbound
- outbound
- both
insights.v1.account_settings:
type: object
properties:
account_sid:
type:
- string
- 'null'
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
description: The unique SID identifier of the Account.
advanced_features:
type:
- boolean
- 'null'
description: A boolean flag indicating whether Advanced Features for Voice Insights are enabled.
voice_trace:
type:
- boolean
- 'null'
description: A boolean flag indicating whether Voice Trace is enabled.
url:
type:
- string
- 'null'
format: uri
description: The URL of this resource.
summary_enum_call_state:
type: string
enum:
- ringing
- completed
- busy
- fail
- noanswer
- canceled
- answered
- undialed
metric_enum_twilio_edge:
type: string
enum:
- unknown_edge
- carrier_edge
- sip_edge
- sdk_edge
- client_edge
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
- 'null'
format: uri
page:
type: integer
page_size:
type: integer
previous_page_url:
type:
- string
- 'null'
format: uri
url:
type: string
format: uri
key:
type: string
ListCallSummariesResponse:
type: object
properties:
call_summaries:
type: array
items:
$ref: '#/components/schemas/insights.v1.call_summaries'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type:
- string
- 'null'
format: uri
page:
type: integer
page_size:
type: integer
previous_page_url:
type:
- string
- 'null'
format: uri
url:
type: string
format: uri
key:
type: string
summary_enum_call_type:
type: string
enum:
- carrier
- sip
- trunking
- client
event_enum_level:
type: string
enum:
- UNKNOWN
- DEBUG
- INFO
- WARNING
- ERROR
insights.v1.call.event:
type: object
properties:
timestamp:
type:
- string
- 'null'
description: Event time.
call_sid:
type:
- string
- 'null'
minLength: 34
maxLength: 34
pattern: ^CA[0-9a-fA-F]{32}$
description: The unique SID identifier of the Call.
account_sid:
type:
- string
- 'null'
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
description: The unique SID identifier of the Account.
edge:
type:
- string
- 'null'
$ref: '#/components/schemas/event_enum_twilio_edge'
description: The Edge of this Event. One of `unknown_edge`, `carrier_edge`, `sip_edge`, `sdk_edge` or `client_edge`.
group:
type:
- string
- 'null'
description: Event group.
level:
type:
- string
- 'null'
$ref: '#/components/schemas/event_enum_level'
description: The Level of this Event. One of `UNKNOWN`,
# --- 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