openapi: 3.0.0
info:
title: Vapi Phone Numbers API
description: Vapi API — Phone Numbers 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:
securitySchemes:
bearer:
scheme: bearer
bearerFormat: Bearer
type: http
description: Retrieve your API Key from [Dashboard](dashboard.vapi.ai).
schemas:
BackoffPlan:
type: object
properties:
type:
type: object
description: 'This is the type of backoff plan to use. Defaults to fixed.
@default fixed'
enum:
- fixed
- exponential
example: fixed
maxRetries:
type: number
description: 'This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries).
@default 0'
minimum: 0
maximum: 10
example: 0
baseDelaySeconds:
type: number
description: This is the base delay in seconds. For linear backoff, this is the delay between each retry. For exponential
backoff, this is the initial delay.
minimum: 0
maximum: 10
example: 1
excludedStatusCodes:
description: 'This is the excluded status codes. If the response status code is in this list, the request will not
be retried.
By default, the request will be retried for any non-2xx status code.'
example:
- 400
- 401
- 403
- 404
type: array
items:
type: object
required:
- type
- maxRetries
- baseDelaySeconds
ByoPhoneNumber:
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
provider:
type: string
description: This is to bring your own phone numbers from your own SIP trunks or Carriers.
enum:
- byo-phone-number
numberE164CheckEnabled:
type: boolean
description: 'This is the flag to toggle the E164 check for the `number` field. This is an advanced property which
should be used if you know your use case requires it.
Use cases:
- `false`: To allow non-E164 numbers like `+001234567890`, `1234`, or `abc`. This is useful for dialing out to
non-E164 numbers on your SIP trunks.
- `true` (default): To allow only E164 numbers like `+14155551234`. This is standard for PSTN calls.
If `false`, the `number` is still required to only contain alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`).
@default true (E164 check is enabled)'
default: true
id:
type: string
description: This is the unique identifier for the phone number.
orgId:
type: string
description: This is the unique identifier for the org that this phone number belongs to.
createdAt:
format: date-time
type: string
description: This is the ISO 8601 date-time string of when the phone number was created.
updatedAt:
format: date-time
type: string
description: This is the ISO 8601 date-time string of when the phone number was last updated.
status:
type: string
description: This is the status of the phone number.
enum:
- active
- activating
- blocked
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: This is the number of the customer.
minLength: 3
maxLength: 40
credentialId:
type: string
description: 'This is the credential of your own SIP trunk or Carrier (type `byo-sip-trunk`) which can be used to
make calls to this phone number.
You can add the SIP trunk or Carrier credential in the Provider Credentials page on the Dashboard to get the credentialId.'
required:
- provider
- id
- orgId
- createdAt
- updatedAt
- credentialId
ContextEngineeringPlanAll:
type: object
properties:
type:
type: string
enum:
- all
required:
- type
ContextEngineeringPlanLastNMessages:
type: object
properties:
type:
type: string
enum:
- lastNMessages
maxMessages:
type: number
description: This is the maximum number of messages to include in the context engineering plan.
minimum: 0
required:
- type
- maxMessages
ContextEngineeringPlanNone:
type: object
properties:
type:
type: string
enum:
- none
required:
- type
CreateByoPhoneNumberDTO:
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
provider:
type: string
description: This is to bring your own phone numbers from your own SIP trunks or Carriers.
enum:
- byo-phone-number
numberE164CheckEnabled:
type: boolean
description: 'This is the flag to toggle the E164 check for the `number` field. This is an advanced property which
should be used if you know your use case requires it.
Use cases:
- `false`: To allow non-E164 numbers like `+001234567890`, `1234`, or `abc`. This is useful for dialing out to
non-E164 numbers on your SIP trunks.
- `true` (default): To allow only E164 numbers like `+14155551234`. This is standard for PSTN calls.
If `false`, the `number` is still required to only contain alphanumeric characters (regex: `/^\+?[a-zA-Z0-9]+$/`).
@default true (E164 check is enabled)'
default: true
number:
type: string
description: This is the number of the customer.
minLength: 3
maxLength: 40
credentialId:
type: string
description: 'This is the credential of your own SIP trunk or Carrier (type `byo-sip-trunk`) which can be used to
make calls to this phone number.
You can add the SIP trunk or Carrier credential in the Provider Credentials page on the Dashboard to get the credentialId.'
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'
required:
- provider
- credentialId
CreateTelnyxPhoneNumberDTO:
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
provider:
type: string
description: This is to use numbers bought on Telnyx.
enum:
- telnyx
number:
type: string
description: These are the digits of the phone number you own on your Telnyx.
credentialId:
type: string
description: This is the credential you added in dashboard.vapi.ai/keys. This is used to configure the number to
send inbound calls to Vapi, make outbound calls and do live call updates like transfers and hangups.
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'
required:
- provider
- number
- credentialId
CreateTwilioPhoneNumberDTO:
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
provider:
type: string
description: This is to use numbers bought on Twilio.
enum:
- twilio
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
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
# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vapi-ai/refs/heads/main/openapi/vapi-phone-numbers-api-openapi.yml