Skip to main content
POST
/
phone-number
Create Phone Number
curl --request POST \
  --url https://api.vapi.ai/phone-number \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fallbackDestination": {
    "type": "number",
    "numberE164CheckEnabled": true,
    "number": "<string>",
    "extension": "<string>",
    "message": "<string>",
    "description": "<string>"
  },
  "provider": "byo-phone-number",
  "numberE164CheckEnabled": true,
  "number": "<string>",
  "credentialId": "<string>",
  "name": "<string>",
  "assistantId": "<string>",
  "squadId": "<string>",
  "serverUrl": "<string>",
  "serverUrlSecret": "<string>"
}
'
{
  "fallbackDestination": {
    "type": "number",
    "numberE164CheckEnabled": true,
    "number": "<string>",
    "extension": "<string>",
    "message": "<string>",
    "description": "<string>"
  },
  "provider": "byo-phone-number",
  "numberE164CheckEnabled": true,
  "id": "<string>",
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "assistantId": "<string>",
  "squadId": "<string>",
  "serverUrl": "<string>",
  "serverUrlSecret": "<string>",
  "number": "<string>",
  "credentialId": "<string>"
}

Authorizations

​
Authorization
string
header
required

Retrieve your API Key from Dashboard.

Body

application/json
​
provider
enum<string>
required

This is to bring your own phone numbers from your own SIP trunks or Carriers.

Available options:
byo-phone-number
​
credentialId
string
required

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.

​
fallbackDestination
object

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.

​
numberE164CheckEnabled
boolean
default:true

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', orabc`. 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 for most standard 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)

​
number
string

This is the number of the customer.

Required string length: 3 - 40
​
name
string

This is the name of the phone number. This is just for your own reference.

Maximum length: 40
​
assistantId
string

This is the assistant that will be used for incoming calls to this phone number.

If neither assistantId nor squadId 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
string

This is the squad that will be used for incoming calls to this phone number.

If neither assistantId nor squadId 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.

​
serverUrl
string

This is the server URL where messages will be sent for calls on this number. This includes the assistant-request message.

You can see the shape of the messages sent in ServerMessage.

This overrides the org.serverUrl. Order of precedence: tool.server.url > assistant.serverUrl > phoneNumber.serverUrl > org.serverUrl.

​
serverUrlSecret
string

This is the secret Vapi will send with every message to your server. It's sent as a header called x-vapi-secret.

Same precedence logic as serverUrl.

Response

201 - application/json
​
provider
enum<string>
required

This is to bring your own phone numbers from your own SIP trunks or Carriers.

Available options:
byo-phone-number
​
id
string
required

This is the unique identifier for the phone number.

​
orgId
string
required

This is the unique identifier for the org that this phone number belongs to.

​
createdAt
string<date-time>
required

This is the ISO 8601 date-time string of when the phone number was created.

​
updatedAt
string<date-time>
required

This is the ISO 8601 date-time string of when the phone number was last updated.

​
credentialId
string
required

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.

​
fallbackDestination
object

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.

​
numberE164CheckEnabled
boolean
default:true

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', orabc`. 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 for most standard 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)

​
name
string

This is the name of the phone number. This is just for your own reference.

Maximum length: 40
​
assistantId
string

This is the assistant that will be used for incoming calls to this phone number.

If neither assistantId nor squadId 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
string

This is the squad that will be used for incoming calls to this phone number.

If neither assistantId nor squadId 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.

​
serverUrl
string

This is the server URL where messages will be sent for calls on this number. This includes the assistant-request message.

You can see the shape of the messages sent in ServerMessage.

This overrides the org.serverUrl. Order of precedence: tool.server.url > assistant.serverUrl > phoneNumber.serverUrl > org.serverUrl.

​
serverUrlSecret
string

This is the secret Vapi will send with every message to your server. It's sent as a header called x-vapi-secret.

Same precedence logic as serverUrl.

​
number
string

This is the number of the customer.

Required string length: 3 - 40