Vapi Phone Numbers API
The Phone Numbers API from Vapi — 3 operation(s) for phone numbers.
OpenAPI Specification
openapi: 3.0.0
info:
title: Vapi Analytics Phone Numbers API
description: Voice AI for developers.
version: '1.0'
contact: {}
servers:
- url: https://api.vapi.ai
tags:
- name: Phone Numbers
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
schema:
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
schema:
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
schema:
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:
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
UpdateTelnyxPhoneNumberDTO:
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'
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.
Server:
type: object
properties:
timeoutSeconds:
type: number
description: 'This is the timeout in seconds for the request. Defaults to 20 seconds.
@default 20'
minimum: 1
maximum: 300
example: 20
credentialId:
type: string
description: The credential ID for server authentication
example: 550e8400-e29b-41d4-a716-446655440000
staticIpAddressesEnabled:
type: boolean
description: 'If enabled, requests will originate from a static set of IPs owned and managed by Vapi.
@default false'
example: false
encryptedPaths:
type: array
description: This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined.
items:
type: string
url:
type: string
description: This is where the request will be sent.
headers:
type: object
description: 'These are the headers to include in the request.
Each key-value pair represents a header name and its value.
Note: Specifying an Authorization header here will override the authorization provided by the `credentialId` (if provided). This is an anti-pattern and should be avoided outside of edge case scenarios.'
backoffPlan:
description: 'This is the backoff plan if the request fails. Defaults to undefined (the request will not be retried).
@default undefined (the request will not be retried)'
allOf:
- $ref: '#/components/schemas/BackoffPlan'
UpdateByoPhoneNumberDTO:
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
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
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.'
TransferDestinationNumber:
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:
- 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 phone number to transfer the call to.
minLength: 3
maxLength: 40
extension:
type: string
description: This is the extension to dial after transferring the call to the `number`.
minLength: 1
maxLength: 10
callerId:
type: string
description: "This is the caller ID to use when transferring the call to the `number`.\n\nUsage:\n- If not provided, the caller ID will be the number the call is coming **from**.\n Example: a customer with number +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller.\n For inbound calls, the caller ID is the customer's number. For outbound calls, the caller ID is the phone number of the assistant.\n- To change this behavior, provide a `callerId`.\n- Set to '{{customer.number}}' to always use the customer's number as the caller ID.\n- Set to '{{phoneNumber.number}}' to always use the phone number of the assistant as the caller ID.\n- Set to any E164 number to always use that number as the caller ID. This needs to be a number that is owned or verified by your Transport provider like Twilio.\n\nFor Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid"
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'
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
- number
SipAuthentication:
type: object
properties:
realm:
type: string
description: This will be expected in the `realm` field of the `authorization` header of the SIP INVITE. Defaults to sip.vapi.ai.
username:
type: string
description: This will be expected in the `username` field of the `authorization` header of the SIP INVITE.
minLength: 20
maxLength: 40
password:
type: string
description: This will be expected to generate the `response` field of the `authorization` header of the SIP INVITE, through digest authentication.
minLength: 20
maxLength: 40
required:
- username
- password
VapiPhoneNumber:
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 create free SIP phone numbers on Vapi.
enum:
- vapi
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
number:
type: string
description: These are the digits of the phone number you purchased from Vapi.
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:
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vapi/refs/heads/main/openapi/vapi-phone-numbers-api-openapi.yml