openapi: 3.0.0
info:
title: Vapi Analytics Phone Numbers API
description: Vapi API — Analytics resource. Voice AI for developers.
version: '1.0'
contact:
name: Vapi
url: https://vapi.ai
servers:
- url: https://api.vapi.ai
security:
- bearer: []
tags:
- name: Phone Numbers
description: Phone Numbers endpoints.
paths:
/phone-number:
post:
operationId: PhoneNumberController_create
summary: Create Phone Number
parameters: []
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateByoPhoneNumberDTO'
title: ByoPhoneNumber
- $ref: '#/components/schemas/CreateTwilioPhoneNumberDTO'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/CreateVonagePhoneNumberDTO'
title: VonagePhoneNumber
- $ref: '#/components/schemas/CreateVapiPhoneNumberDTO'
title: VapiPhoneNumber
- $ref: '#/components/schemas/CreateTelnyxPhoneNumberDTO'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/CreateByoPhoneNumberDTO'
twilio: '#/components/schemas/CreateTwilioPhoneNumberDTO'
vonage: '#/components/schemas/CreateVonagePhoneNumberDTO'
vapi: '#/components/schemas/CreateVapiPhoneNumberDTO'
telnyx: '#/components/schemas/CreateTelnyxPhoneNumberDTO'
responses:
'201':
description: ''
content:
application/json:
schema:
title: PhoneNumber
oneOf:
- $ref: '#/components/schemas/ByoPhoneNumber'
title: ByoPhoneNumber
- $ref: '#/components/schemas/TwilioPhoneNumber'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/VonagePhoneNumber'
title: VonagePhoneNumber
- $ref: '#/components/schemas/VapiPhoneNumber'
title: VapiPhoneNumber
- $ref: '#/components/schemas/TelnyxPhoneNumber'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/ByoPhoneNumber'
twilio: '#/components/schemas/TwilioPhoneNumber'
vonage: '#/components/schemas/VonagePhoneNumber'
vapi: '#/components/schemas/VapiPhoneNumber'
telnyx: '#/components/schemas/TelnyxPhoneNumber'
tags:
- Phone Numbers
security:
- bearer: []
get:
operationId: PhoneNumberController_findAll
summary: List Phone Numbers
parameters:
- name: limit
required: false
in: query
description: This is the maximum number of items to return. Defaults to 100.
schema:
minimum: 0
maximum: 1000
type: number
- name: createdAtGt
required: false
in: query
description: This will return items where the createdAt is greater than the specified value.
schema:
format: date-time
type: string
- name: createdAtLt
required: false
in: query
description: This will return items where the createdAt is less than the specified value.
schema:
format: date-time
type: string
- name: createdAtGe
required: false
in: query
description: This will return items where the createdAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: createdAtLe
required: false
in: query
description: This will return items where the createdAt is less than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtGt
required: false
in: query
description: This will return items where the updatedAt is greater than the specified value.
schema:
format: date-time
type: string
- name: updatedAtLt
required: false
in: query
description: This will return items where the updatedAt is less than the specified value.
schema:
format: date-time
type: string
- name: updatedAtGe
required: false
in: query
description: This will return items where the updatedAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtLe
required: false
in: query
description: This will return items where the updatedAt is less than or equal to the specified value.
schema:
format: date-time
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
title: PhoneNumber
oneOf:
- $ref: '#/components/schemas/ByoPhoneNumber'
title: ByoPhoneNumber
- $ref: '#/components/schemas/TwilioPhoneNumber'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/VonagePhoneNumber'
title: VonagePhoneNumber
- $ref: '#/components/schemas/VapiPhoneNumber'
title: VapiPhoneNumber
- $ref: '#/components/schemas/TelnyxPhoneNumber'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/ByoPhoneNumber'
twilio: '#/components/schemas/TwilioPhoneNumber'
vonage: '#/components/schemas/VonagePhoneNumber'
vapi: '#/components/schemas/VapiPhoneNumber'
telnyx: '#/components/schemas/TelnyxPhoneNumber'
tags:
- Phone Numbers
security:
- bearer: []
/v2/phone-number:
get:
operationId: PhoneNumberController_findAllPaginated
summary: List Phone Numbers
parameters:
- name: search
required: false
in: query
description: This will search phone numbers by name, number, or SIP URI (partial match, case-insensitive).
schema:
maxLength: 100
type: string
- name: page
required: false
in: query
description: This is the page number to return. Defaults to 1.
schema:
minimum: 1
type: number
- name: sortOrder
required: false
in: query
description: This is the sort order for pagination. Defaults to 'DESC'.
schema:
enum:
- ASC
- DESC
type: string
- name: sortBy
required: false
in: query
description: This is the column to sort by. Defaults to 'createdAt'.
schema:
enum:
- createdAt
- duration
- cost
type: string
- name: limit
required: false
in: query
description: This is the maximum number of items to return. Defaults to 100.
schema:
minimum: 0
maximum: 1000
type: number
- name: createdAtGt
required: false
in: query
description: This will return items where the createdAt is greater than the specified value.
schema:
format: date-time
type: string
- name: createdAtLt
required: false
in: query
description: This will return items where the createdAt is less than the specified value.
schema:
format: date-time
type: string
- name: createdAtGe
required: false
in: query
description: This will return items where the createdAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: createdAtLe
required: false
in: query
description: This will return items where the createdAt is less than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtGt
required: false
in: query
description: This will return items where the updatedAt is greater than the specified value.
schema:
format: date-time
type: string
- name: updatedAtLt
required: false
in: query
description: This will return items where the updatedAt is less than the specified value.
schema:
format: date-time
type: string
- name: updatedAtGe
required: false
in: query
description: This will return items where the updatedAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtLe
required: false
in: query
description: This will return items where the updatedAt is less than or equal to the specified value.
schema:
format: date-time
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberPaginatedResponse'
tags:
- Phone Numbers
security:
- bearer: []
/phone-number/{id}:
get:
operationId: PhoneNumberController_findOne
summary: Get Phone Number
parameters:
- name: id
required: true
in: path
description: The unique identifier for the resource.
schema:
format: uuid
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: PhoneNumber
oneOf:
- $ref: '#/components/schemas/ByoPhoneNumber'
title: ByoPhoneNumber
- $ref: '#/components/schemas/TwilioPhoneNumber'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/VonagePhoneNumber'
title: VonagePhoneNumber
- $ref: '#/components/schemas/VapiPhoneNumber'
title: VapiPhoneNumber
- $ref: '#/components/schemas/TelnyxPhoneNumber'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/ByoPhoneNumber'
twilio: '#/components/schemas/TwilioPhoneNumber'
vonage: '#/components/schemas/VonagePhoneNumber'
vapi: '#/components/schemas/VapiPhoneNumber'
telnyx: '#/components/schemas/TelnyxPhoneNumber'
tags:
- Phone Numbers
security:
- bearer: []
patch:
operationId: PhoneNumberController_update
summary: Update Phone Number
parameters:
- name: id
required: true
in: path
description: The unique identifier for the resource.
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UpdateByoPhoneNumberDTO'
title: ByoPhoneNumber
- $ref: '#/components/schemas/UpdateTwilioPhoneNumberDTO'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/UpdateVonagePhoneNumberDTO'
title: VonagePhoneNumber
- $ref: '#/components/schemas/UpdateVapiPhoneNumberDTO'
title: VapiPhoneNumber
- $ref: '#/components/schemas/UpdateTelnyxPhoneNumberDTO'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/UpdateByoPhoneNumberDTO'
twilio: '#/components/schemas/UpdateTwilioPhoneNumberDTO'
vonage: '#/components/schemas/UpdateVonagePhoneNumberDTO'
vapi: '#/components/schemas/UpdateVapiPhoneNumberDTO'
telnyx: '#/components/schemas/UpdateTelnyxPhoneNumberDTO'
responses:
'200':
description: ''
content:
application/json:
schema:
title: PhoneNumber
oneOf:
- $ref: '#/components/schemas/ByoPhoneNumber'
title: ByoPhoneNumber
- $ref: '#/components/schemas/TwilioPhoneNumber'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/VonagePhoneNumber'
title: VonagePhoneNumber
- $ref: '#/components/schemas/VapiPhoneNumber'
title: VapiPhoneNumber
- $ref: '#/components/schemas/TelnyxPhoneNumber'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/ByoPhoneNumber'
twilio: '#/components/schemas/TwilioPhoneNumber'
vonage: '#/components/schemas/VonagePhoneNumber'
vapi: '#/components/schemas/VapiPhoneNumber'
telnyx: '#/components/schemas/TelnyxPhoneNumber'
tags:
- Phone Numbers
security:
- bearer: []
delete:
operationId: PhoneNumberController_remove
summary: Delete Phone Number
parameters:
- name: id
required: true
in: path
description: The unique identifier for the resource.
schema:
format: uuid
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: PhoneNumber
oneOf:
- $ref: '#/components/schemas/ByoPhoneNumber'
title: ByoPhoneNumber
- $ref: '#/components/schemas/TwilioPhoneNumber'
title: TwilioPhoneNumber
- $ref: '#/components/schemas/VonagePhoneNumber'
title: VonagePhoneNumber
- $ref: '#/components/schemas/VapiPhoneNumber'
title: VapiPhoneNumber
- $ref: '#/components/schemas/TelnyxPhoneNumber'
title: TelnyxPhoneNumber
discriminator:
propertyName: provider
mapping:
byo-phone-number: '#/components/schemas/ByoPhoneNumber'
twilio: '#/components/schemas/TwilioPhoneNumber'
vonage: '#/components/schemas/VonagePhoneNumber'
vapi: '#/components/schemas/VapiPhoneNumber'
telnyx: '#/components/schemas/TelnyxPhoneNumber'
tags:
- Phone Numbers
security:
- bearer: []
components:
schemas:
TransferDestinationSip:
type: object
properties:
message:
description: 'This is spoken to the customer before connecting them to the destination.
Usage:
- If this is not provided and transfer tool messages is not provided, default is "Transferring the call now".
- If set to "", nothing is spoken. This is useful when you want to silently transfer. This is especially useful when transferring between assistants in a squad. In this scenario, you likely also want to set `assistant.firstMessageMode=assistant-speaks-first-with-model-generated-message` for the destination assistant.
This accepts a string or a ToolMessageStart class. Latter is useful if you want to specify multiple messages for different languages through the `contents` field.'
oneOf:
- type: string
- $ref: '#/components/schemas/CustomMessage'
type:
type: string
enum:
- sip
sipUri:
type: string
description: This is the SIP URI to transfer the call to.
callerId:
type: string
description: 'This is the caller ID to use when transferring the call to the `sipUri`.
Usage:
- If not provided, the caller ID will be determined by the SIP infrastructure.
- Set to ''{{customer.number}}'' to always use the customer''s number as the caller ID.
- Set to ''{{phoneNumber.number}}'' to always use the phone number of the assistant as the caller ID.
- Set to any E164 number to always use that number as the caller ID.
Only applicable when `transferPlan.sipVerb=''dial''`. Not applicable for SIP REFER.'
maxLength: 40
transferPlan:
description: 'This configures how transfer is executed and the experience of the destination party receiving the call. Defaults to `blind-transfer`.
@default `transferPlan.mode=''blind-transfer''`'
allOf:
- $ref: '#/components/schemas/TransferPlan'
sipHeaders:
type: object
description: These are custom headers to be added to SIP refer during transfer call.
description:
type: string
description: This is the description of the destination, used by the AI to choose when and how to transfer the call.
required:
- type
- sipUri
UpdateVapiPhoneNumberDTO:
type: object
properties:
fallbackDestination:
description: 'This is the fallback destination an inbound call will be transferred to if:
1. `assistantId` is not set
2. `squadId` is not set
3. and, `assistant-request` message to the `serverUrl` fails
If this is not set and above conditions are met, the inbound call is hung up with an error message.'
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
hooks:
type: array
description: This is the hooks that will be used for incoming calls to this phone number.
items:
oneOf:
- $ref: '#/components/schemas/PhoneNumberHookCallRinging'
title: PhoneNumberHookCallRinging
- $ref: '#/components/schemas/PhoneNumberHookCallEnding'
title: PhoneNumberHookCallEnding
name:
type: string
description: This is the name of the phone number. This is just for your own reference.
maxLength: 40
assistantId:
type: string
description: 'This is the assistant that will be used for incoming calls to this phone number.
If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
workflowId:
type: string
description: 'This is the workflow that will be used for incoming calls to this phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
squadId:
type: string
description: 'This is the squad that will be used for incoming calls to this phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
server:
description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema.
The order of precedence is:
1. assistant.server
2. phoneNumber.server
3. org.server'
allOf:
- $ref: '#/components/schemas/Server'
sipUri:
type: string
description: 'This is the SIP URI of the phone number. You can SIP INVITE this. The assistant attached to this number will answer.
This is case-insensitive.'
authentication:
description: 'This enables authentication for incoming SIP INVITE requests to the `sipUri`.
If not set, any username/password to the 401 challenge of the SIP INVITE will be accepted.'
allOf:
- $ref: '#/components/schemas/SipAuthentication'
UpdateTwilioPhoneNumberDTO:
type: object
properties:
fallbackDestination:
description: 'This is the fallback destination an inbound call will be transferred to if:
1. `assistantId` is not set
2. `squadId` is not set
3. and, `assistant-request` message to the `serverUrl` fails
If this is not set and above conditions are met, the inbound call is hung up with an error message.'
oneOf:
- $ref: '#/components/schemas/TransferDestinationNumber'
title: NumberTransferDestination
- $ref: '#/components/schemas/TransferDestinationSip'
title: SipTransferDestination
hooks:
type: array
description: This is the hooks that will be used for incoming calls to this phone number.
items:
oneOf:
- $ref: '#/components/schemas/PhoneNumberHookCallRinging'
title: PhoneNumberHookCallRinging
- $ref: '#/components/schemas/PhoneNumberHookCallEnding'
title: PhoneNumberHookCallEnding
smsEnabled:
type: boolean
description: 'Controls whether Vapi sets the messaging webhook URL on the Twilio number during import.
If set to `false`, Vapi will not update the Twilio messaging URL, leaving it as is.
If `true` or omitted (default), Vapi will configure both the voice and messaging URLs.
@default true'
default: true
name:
type: string
description: This is the name of the phone number. This is just for your own reference.
maxLength: 40
assistantId:
type: string
description: 'This is the assistant that will be used for incoming calls to this phone number.
If neither `assistantId`, `squadId` nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
workflowId:
type: string
description: 'This is the workflow that will be used for incoming calls to this phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
squadId:
type: string
description: 'This is the squad that will be used for incoming calls to this phone number.
If neither `assistantId`, `squadId`, nor `workflowId` is set, `assistant-request` will be sent to your Server URL. Check `ServerMessage` and `ServerMessageResponse` for the shape of the message and response that is expected.'
server:
description: 'This is where Vapi will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema.
The order of precedence is:
1. assistant.server
2. phoneNumber.server
3. org.server'
allOf:
- $ref: '#/components/schemas/Server'
number:
type: string
description: These are the digits of the phone number you own on your Twilio.
twilioAccountSid:
type: string
description: This is the Twilio Account SID for the phone number.
twilioAuthToken:
type: string
description: This is the Twilio Auth Token for the phone number.
twilioApiKey:
type: string
description: This is the Twilio API Key for the phone number.
twilioApiSecret:
type: string
description: This is the Twilio API Secret for the phone number.
TransferPlan:
type: object
properties:
mode:
type: string
description: 'This configures how transfer is executed and the experience of the destination party receiving the call.
Usage:
- `blind-transfer`: The assistant forwards the call to the destination without any message or summary.
- `blind-transfer-add-summary-to-sip-header`: The assistant forwards the call to the destination and adds a SIP header X-Transfer-Summary to the call to include the summary.
- `warm-transfer-say-message`: The assistant dials the destination, delivers the `message` to the destination party, connects the customer, and leaves the call.
- `warm-transfer-say-summary`: The assistant dials the destination, provides a summary of the call to the destination party, connects the customer, and leaves the call.
- `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`: The assistant dials the destination, waits for the operator to speak, delivers the `message` to the destination party, and then connects the customer.
- `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`: The assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer.
- `warm-transfer-twiml`: The assistant dials the destination, executes the twiml instructions on the destination call leg, connects the customer, and leaves the call.
- `warm-transfer-experimental`: The assistant puts the customer on hold, dials the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the `fallbackMessage` to the customer and optionally ends the call.
@default ''blind-transfer'''
enum:
- blind-transfer
- blind-transfer-add-summary-to-sip-header
- warm-transfer-say-message
- warm-transfer-say-summary
- warm-transfer-twiml
- warm-transfer-wait-for-operator-to-speak-first-and-then-say-message
- warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary
- warm-transfer-experimental
message:
description: 'This is the message the assistant will deliver to the destination party before connecting the customer.
Usage:
- Used only when `mode` is `blind-transfer-add-summary-to-sip-header`, `warm-transfer-say-message`, `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`, or `warm-transfer-experimental`.'
oneOf:
- type: string
- $ref: '#/components/schemas/CustomMessage'
timeout:
type: number
description: 'This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary
@default 60'
minimum: 1
maximum: 600
default: 60
sipVerb:
type: object
description: 'This specifies the SIP verb to use while transferring the call.
- ''refer'': Uses SIP REFER to transfer the call (default)
- ''bye'': Ends current call with SIP BYE
- ''dial'': Uses SIP DIAL to transfer the call'
default: refer
enum:
- refer
- bye
- dial
dialTimeout:
type: number
description: 'This sets the timeout for the dial operation in seconds. This is the duration the call will ring before timing out.
Only applicable when `sipVerb=''dial''`. Not applicable for SIP REFER or BYE.
@default 60'
minimum: 1
maximum: 600
default: 60
holdAudioUrl:
type: string
description: 'This is the URL to an audio file played while the customer is on hold during transfer.
Usage:
- Used only when `mode` is `warm-transfer-experimental`.
- Used when transferring calls to play hold audio for the customer.
- Must be a publicly accessible URL to an audio file.
- Supported formats: MP3 and WAV.
- If not provided, the default hold audio will be used.'
transferCompleteAudioUrl:
type: string
description: 'This is the URL to an audio file played after the warm transfer message or summary is delivered to the destination party.
It can be used to play a custom sound like ''beep'' to notify that the transfer is complete.
Usage:
- Used only when `mode` is `warm-transfer-experimental`.
- Used when transferring calls to play hold audio for the destination party.
- Must be a publicly accessible URL to an audio file.
- Supported formats: MP3 and WAV.'
contextEngineeringPlan:
description: 'This is the plan for manipulating the message context before initiating the warm transfer.
Usage:
- Used only when `mode` is `warm-transfer-experimental`.
- These messages will automatically be added to the transferAssistant''s system message.
- If ''none'', we will not add any transcript to the transferAssistant''s system message.
- If you want to provide your own messages, use transferAssistant.model.messages instead.
@default { type: ''all'' }'
oneOf:
- $ref: '#/components/schemas/ContextEngineeringPlanLastNMessages'
title: Last N Messages
- $ref: '#/components/schemas/ContextEngineeringPlanNone'
title: None
- $ref: '#/components/schemas/ContextEngineeringPlanAll'
title: All
twiml:
type: string
description: 'This is the TwiML instructions to execute on the destination call leg before connecting the customer.
Usage:
- Used only when `mode` is `warm-transfer-twiml`.
- Supports only `Play`, `Say`, `Gather`, `Hangup` and `Pause` verbs.
- Maximum length is 4096 characters.
Example:
```
<Say voice="alice" language="en-US">Hello, transferring a customer to you.</Say>
<Pause length="2"/>
<Say>They called about billing questions.</Say>
```'
maxLength: 4096
summaryPlan:
description: 'This is the plan for generating a summary of the call to present to the destination party.
Usage:
- Used only when `mode` is `blind-transfer-add-summary-to-sip-header` or `warm-transfer-say-summary` or `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary` or `warm-transfer-experimental`.'
allOf:
- $ref: '#/components/schemas/SummaryPlan'
sipHeadersInReferToEnabled:
type: boolean
description: 'This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params.
@default false'
fallbackPlan:
description: 'This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human).
Usage:
- Used only when `mode` is `warm-tran
# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vapi-ai/refs/heads/main/openapi/vapi-ai-phone-numbers-api-openapi.yml