--- title: "List Phone Numbers" method: GET path: "/v2/phone-number" tags: ["Phone Numbers"] --- # List Phone Numbers `GET /v2/phone-number` ## Query parameters - `search` string - `page` number - `sortOrder` 'ASC' | 'DESC' - `sortBy` 'createdAt' | 'duration' | 'cost' - `limit` number - `createdAtGt` string, date-time - `createdAtLt` string, date-time - `createdAtGe` string, date-time - `createdAtLe` string, date-time - `updatedAtGt` string, date-time - `updatedAtLt` string, date-time - `updatedAtGe` string, date-time - `updatedAtLe` string, date-time ## Response `200` - PhoneNumberPaginatedResponse - `results` union[], required — A list of phone numbers, which can be of any provider type. - union - ByoPhoneNumber - `fallbackDestination` union — 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. - TransferDestinationNumber - `message` union — 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. - … - `type` 'number', required - `numberE164CheckEnabled` boolean — 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) - `number` string, required — This is the phone number to transfer the call to. - `extension` string — This is the extension to dial after transferring the call to the `number`. - `callerId` string — This is the caller ID to use when transferring the call to the `number`. Usage: - If not provided, the caller ID will be the number the call is coming **from**. Example: a customer with number +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller. For inbound calls, the caller ID is the customer's number. For outbound calls, the caller ID is the phone number of the assistant. - To change this behavior, provide a `callerId`. - 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. This needs to be a number that is owned or verified by your Transport provider like Twilio. For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid - `transferPlan` TransferPlan - … - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - TransferDestinationSip - `message` union — 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. - … - `type` 'sip', required - `sipUri` string, required — This is the SIP URI to transfer the call to. - `callerId` string — 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. - `transferPlan` TransferPlan - … - `sipHeaders` object — These are custom headers to be added to SIP refer during transfer call. - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - `hooks` union[] — This is the hooks that will be used for incoming calls to this phone number. - union - PhoneNumberHookCallRinging - … - PhoneNumberHookCallEnding - … - `provider` 'byo-phone-number', required — This is to bring your own phone numbers from your own SIP trunks or Carriers. - `numberE164CheckEnabled` boolean — 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) - `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. - `status` 'active' | 'activating' | 'blocked' — This is the status of the phone number. - `name` string — This is the name of the phone number. This is just for your own reference. - `assistantId` string — 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` string — 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` string — 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` Server - `timeoutSeconds` number — This is the timeout in seconds for the request. Defaults to 20 seconds. @default 20 - `credentialId` string — The credential ID for server authentication - `staticIpAddressesEnabled` boolean — If enabled, requests will originate from a static set of IPs owned and managed by Vapi. @default false - `encryptedPaths` string[] — This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined. - `url` string — This is where the request will be sent. - `headers` object — 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` BackoffPlan - `type` object, required — This is the type of backoff plan to use. Defaults to fixed. @default fixed - `maxRetries` number, required — This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries). @default 0 - `baseDelaySeconds` number, required — 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. - `excludedStatusCodes` object[] — 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. - … - `number` string — This is the number of the customer. - `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. - TwilioPhoneNumber - `fallbackDestination` union — 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. - TransferDestinationNumber - `message` union — 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. - … - `type` 'number', required - `numberE164CheckEnabled` boolean — 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) - `number` string, required — This is the phone number to transfer the call to. - `extension` string — This is the extension to dial after transferring the call to the `number`. - `callerId` string — This is the caller ID to use when transferring the call to the `number`. Usage: - If not provided, the caller ID will be the number the call is coming **from**. Example: a customer with number +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller. For inbound calls, the caller ID is the customer's number. For outbound calls, the caller ID is the phone number of the assistant. - To change this behavior, provide a `callerId`. - 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. This needs to be a number that is owned or verified by your Transport provider like Twilio. For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid - `transferPlan` TransferPlan - … - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - TransferDestinationSip - `message` union — 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. - … - `type` 'sip', required - `sipUri` string, required — This is the SIP URI to transfer the call to. - `callerId` string — 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. - `transferPlan` TransferPlan - … - `sipHeaders` object — These are custom headers to be added to SIP refer during transfer call. - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - `hooks` union[] — This is the hooks that will be used for incoming calls to this phone number. - union - PhoneNumberHookCallRinging - … - PhoneNumberHookCallEnding - … - `provider` 'twilio', required — This is to use numbers bought on Twilio. - `smsEnabled` boolean — 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 - `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. - `status` 'active' | 'activating' | 'blocked' — This is the status of the phone number. - `twilioAuthToken` string — This is the Twilio Auth Token for the phone number. - `twilioApiKey` string — This is the Twilio API Key for the phone number. - `twilioApiSecret` string — This is the Twilio API Secret for the phone number. - `name` string — This is the name of the phone number. This is just for your own reference. - `assistantId` string — 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` string — 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` string — 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` Server - `timeoutSeconds` number — This is the timeout in seconds for the request. Defaults to 20 seconds. @default 20 - `credentialId` string — The credential ID for server authentication - `staticIpAddressesEnabled` boolean — If enabled, requests will originate from a static set of IPs owned and managed by Vapi. @default false - `encryptedPaths` string[] — This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined. - `url` string — This is where the request will be sent. - `headers` object — 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` BackoffPlan - `type` object, required — This is the type of backoff plan to use. Defaults to fixed. @default fixed - `maxRetries` number, required — This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries). @default 0 - `baseDelaySeconds` number, required — 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. - `excludedStatusCodes` object[] — 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. - … - `number` string, required — These are the digits of the phone number you own on your Twilio. - `twilioAccountSid` string, required — This is the Twilio Account SID for the phone number. - VonagePhoneNumber - `fallbackDestination` union — 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. - TransferDestinationNumber - `message` union — 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. - … - `type` 'number', required - `numberE164CheckEnabled` boolean — 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) - `number` string, required — This is the phone number to transfer the call to. - `extension` string — This is the extension to dial after transferring the call to the `number`. - `callerId` string — This is the caller ID to use when transferring the call to the `number`. Usage: - If not provided, the caller ID will be the number the call is coming **from**. Example: a customer with number +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller. For inbound calls, the caller ID is the customer's number. For outbound calls, the caller ID is the phone number of the assistant. - To change this behavior, provide a `callerId`. - 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. This needs to be a number that is owned or verified by your Transport provider like Twilio. For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid - `transferPlan` TransferPlan - … - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - TransferDestinationSip - `message` union — 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. - … - `type` 'sip', required - `sipUri` string, required — This is the SIP URI to transfer the call to. - `callerId` string — 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. - `transferPlan` TransferPlan - … - `sipHeaders` object — These are custom headers to be added to SIP refer during transfer call. - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - `hooks` union[] — This is the hooks that will be used for incoming calls to this phone number. - union - PhoneNumberHookCallRinging - … - PhoneNumberHookCallEnding - … - `provider` 'vonage', required — This is to use numbers bought on Vonage. - `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. - `status` 'active' | 'activating' | 'blocked' — This is the status of the phone number. - `name` string — This is the name of the phone number. This is just for your own reference. - `assistantId` string — 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` string — 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` string — 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` Server - `timeoutSeconds` number — This is the timeout in seconds for the request. Defaults to 20 seconds. @default 20 - `credentialId` string — The credential ID for server authentication - `staticIpAddressesEnabled` boolean — If enabled, requests will originate from a static set of IPs owned and managed by Vapi. @default false - `encryptedPaths` string[] — This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined. - `url` string — This is where the request will be sent. - `headers` object — 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` BackoffPlan - `type` object, required — This is the type of backoff plan to use. Defaults to fixed. @default fixed - `maxRetries` number, required — This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries). @default 0 - `baseDelaySeconds` number, required — 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. - `excludedStatusCodes` object[] — 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. - … - `number` string, required — These are the digits of the phone number you own on your Vonage. - `credentialId` string, required — 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. - VapiPhoneNumber - `fallbackDestination` union — 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. - TransferDestinationNumber - `message` union — 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. - … - `type` 'number', required - `numberE164CheckEnabled` boolean — 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) - `number` string, required — This is the phone number to transfer the call to. - `extension` string — This is the extension to dial after transferring the call to the `number`. - `callerId` string — This is the caller ID to use when transferring the call to the `number`. Usage: - If not provided, the caller ID will be the number the call is coming **from**. Example: a customer with number +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller. For inbound calls, the caller ID is the customer's number. For outbound calls, the caller ID is the phone number of the assistant. - To change this behavior, provide a `callerId`. - 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. This needs to be a number that is owned or verified by your Transport provider like Twilio. For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid - `transferPlan` TransferPlan - … - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - TransferDestinationSip - `message` union — 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. - … - `type` 'sip', required - `sipUri` string, required — This is the SIP URI to transfer the call to. - `callerId` string — 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. - `transferPlan` TransferPlan - … - `sipHeaders` object — These are custom headers to be added to SIP refer during transfer call. - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - `hooks` union[] — This is the hooks that will be used for incoming calls to this phone number. - union - PhoneNumberHookCallRinging - … - PhoneNumberHookCallEnding - … - `provider` 'vapi', required — This is to create free SIP phone numbers on Vapi. - `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. - `status` 'active' | 'activating' | 'blocked' — This is the status of the phone number. - `number` string — These are the digits of the phone number you purchased from Vapi. - `name` string — This is the name of the phone number. This is just for your own reference. - `assistantId` string — 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` string — 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` string — 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` Server - `timeoutSeconds` number — This is the timeout in seconds for the request. Defaults to 20 seconds. @default 20 - `credentialId` string — The credential ID for server authentication - `staticIpAddressesEnabled` boolean — If enabled, requests will originate from a static set of IPs owned and managed by Vapi. @default false - `encryptedPaths` string[] — This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined. - `url` string — This is where the request will be sent. - `headers` object — 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` BackoffPlan - `type` object, required — This is the type of backoff plan to use. Defaults to fixed. @default fixed - `maxRetries` number, required — This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries). @default 0 - `baseDelaySeconds` number, required — 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. - `excludedStatusCodes` object[] — 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. - … - `numberDesiredAreaCode` string — This is the area code of the phone number to purchase. - `sipUri` string — 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` SipAuthentication - `realm` string — This will be expected in the `realm` field of the `authorization` header of the SIP INVITE. Defaults to the SIP realm of the Vapi region serving the request (e.g. `sip.vapi.ai` for US, `sip.eu.vapi.ai` for EU). - `username` string, required — This will be expected in the `username` field of the `authorization` header of the SIP INVITE. - `password` string, required — This will be expected to generate the `response` field of the `authorization` header of the SIP INVITE, through digest authentication. - TelnyxPhoneNumber - `fallbackDestination` union — 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. - TransferDestinationNumber - `message` union — 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. - … - `type` 'number', required - `numberE164CheckEnabled` boolean — 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) - `number` string, required — This is the phone number to transfer the call to. - `extension` string — This is the extension to dial after transferring the call to the `number`. - `callerId` string — This is the caller ID to use when transferring the call to the `number`. Usage: - If not provided, the caller ID will be the number the call is coming **from**. Example: a customer with number +14151111111 calls in to and the assistant transfers out to +16470000000. +16470000000 will see +14151111111 as the caller. For inbound calls, the caller ID is the customer's number. For outbound calls, the caller ID is the phone number of the assistant. - To change this behavior, provide a `callerId`. - 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. This needs to be a number that is owned or verified by your Transport provider like Twilio. For Twilio, you can read up more here: https://www.twilio.com/docs/voice/twiml/dial#callerid - `transferPlan` TransferPlan - … - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - TransferDestinationSip - `message` union — 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. - … - `type` 'sip', required - `sipUri` string, required — This is the SIP URI to transfer the call to. - `callerId` string — 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. - `transferPlan` TransferPlan - … - `sipHeaders` object — These are custom headers to be added to SIP refer during transfer call. - `name` string — This is the name of the transfer destination. This is just for your own reference. Usage: - Optional. Stored with the destination wherever it is supplied. For `number` and `sip` destinations it is also persisted on the transfer record in the call artifact after a transfer and displayed in the dashboard call log (on the transfer divider in the transcript view) alongside the destination. When omitted, everything behaves exactly as before. - Display-only. Unlike `description`, it is never included in prompts or tool descriptions and has no effect on model behavior or destination choice. - `description` string — This is the description of the destination, used by the AI to choose when and how to transfer the call. - `hooks` union[] — This is the hooks that will be used for incoming calls to this phone number. - union - PhoneNumberHookCallRinging - … - PhoneNumberHookCallEnding - … - `provider` 'telnyx', required — This is to use numbers bought on Telnyx. - `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. - `status` 'active' | 'activating' | 'blocked' — This is the status of the phone number. - `name` string — This is the name of the phone number. This is just for your own reference. - `assistantId` string — 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` string — 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` string — 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` Server - `timeoutSeconds` number — This is the timeout in seconds for the request. Defaults to 20 seconds. @default 20 - `credentialId` string — The credential ID for server authentication - `staticIpAddressesEnabled` boolean — If enabled, requests will originate from a static set of IPs owned and managed by Vapi. @default false - `encryptedPaths` string[] — This is the paths to encrypt in the request body if credentialId and encryptionPlan are defined. - `url` string — This is where the request will be sent. - `headers` object — 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` BackoffPlan - `type` object, required — This is the type of backoff plan to use. Defaults to fixed. @default fixed - `maxRetries` number, required — This is the maximum number of retries to attempt if the request fails. Defaults to 0 (no retries). @default 0 - `baseDelaySeconds` number, required — 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. - `excludedStatusCodes` object[] — 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. - … - `number` string, required — These are the digits of the phone number you own on your Telnyx. - `credentialId` string, required — 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. - `metadata` PaginationMeta, required - `itemsPerPage` number, required - `totalItems` number, required - `currentPage` number, required - `totalPages` number - `hasNextPage` boolean - `nextCursor` string — Opaque cursor for the next page under keyset pagination (PRO-3163). Pass it back as the `cursor` query param to fetch the next page without an OFFSET scan. Present only when a further page likely exists. - `sortOrder` 'ASC' | 'DESC' - `itemsBeyondRetention` boolean - `createdAtLe` string, date-time - `createdAtGe` string, date-time ## Changes > 57 revisions in range; 2 not diffed, 14 could not be searched. - **2025-11-18** `4c188bb946f2` — 30 info - added the optional property `results/items/oneOf[#/components/schemas/ByoPhoneNumber]/fallbackDestination/oneOf[subschema #1: NumberTransferDestination]/transferPlan/allOf[#/components/schemas/TransferPlan]/dialTimeout` to the response with the `200` status - added the optional property `results/items/oneOf[#/components/schemas/ByoPhoneNumber]/fallbackDestination/oneOf[subschema #2: SipTransferDestination]/transferPlan/allOf[#/components/schemas/TransferPlan]/dialTimeout` to the response with the `200` status - added the optional property `results/items/oneOf[#/components/schemas/ByoPhoneNumber]/hooks/items/oneOf[subschema #1: PhoneNumberHookCallRinging]/do/items/oneOf[subschema #1: TransferPhoneNumberHookAction]/destination/oneOf[subschema #1: NumberTransferDestination]/transferPlan/allOf[#/components/schemas/TransferPlan]/dialTimeout` to the response with the `200` status - added the optional property `results/items/oneOf[#/components/schemas/ByoPhoneNumber]/hooks/items/oneOf[subschema #1: PhoneNumberHookCallRinging]/do/items/oneOf[subschema #1: TransferPhoneNumberHookAction]/destination/oneOf[subschema #2: SipTransferDestination]/transferPlan/allOf[#/components/schemas/TransferPlan]/dialTimeout` to the response with the `200` status - …26 more - …earlier changes not shown [Full history](https://skmtc.dev/vapiai/apis/vapi-api/changes/v2/phone-number/get.md) --- [API](https://skmtc.dev/vapiai/apis/vapi-api.md) · [All operations](https://skmtc.dev/vapiai/apis/vapi-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vapiai/vapi-api/revisions/872ff45af53b/schema)