Numbers

Numbers are a key concept to understand when working with the Vonage Voice API. The following points should be considered before developing your Vonage Application.

Formatting

Within the Vonage Voice (API or SIP Trunking) all numbers are in E.164 format. This means that numbers:

  • Omit both a leading + and the international access code such as 00 or 001.
  • Contain no special characters, such as a space, () or -

For example, a US number would have the format 14155550101. A UK number would have the format 447700900123.

If you are unsure how to format the number, the Number Insight API can be used to find correct information about a number.

Vonage Numbers

Vonage offers rental numbers located in many countries around the world. In some countries, the numbers may be enabled for SMS or Voice only, or in others, they will support both.

Vonage can also provide numbers in both 'landline' and 'mobile' ranges for many countries. You can search for and rent an available number:

Outgoing Caller ID

When making an outbound call, the Caller ID is the from value in the Make a call API or connect actions for Voice API. It can also be found in the SIP INVITE for SIP Trunking; it will be in the PAI header if set, otherwise it will be in the From header. You can use the following numbers as Caller ID:

  • A Vonage Number associated with your account with no limitation on outbound calling (see Limitations field in Buy Numbers page or check with Support).
  • A non-Vonage number after providing the required information on proof of ownership. Subject to geographical restrictions, contact Support to get your number registered as Verified Caller ID.
  • Original Caller ID of the party calling your Vonage number (only applicable for phone endpoint type). This is helpful for call forwarding or call tracking scenarios. For example, when you receive a call from 15551111111 to your Vonage number 15552222222, you can make an outbound call with connect action to a number 15553333333 using original Caller ID 15551111111 as your from number.

Note: This feature is only supported for domestic calls — meaning all three numbers must be within the same country and not subject to restrictions imposed by local regulators.

Any other number used as Caller ID will lead to the call being blocked.

Incoming Caller ID

To use a number you have rented from Vonage with your voice application, you need to link that number to the application via the Dashboard on the Application page, or by using the Numbers API. For SIP Trunking, you should link the number to your SIP domain via the SIP Dashboard. You can link multiple numbers to the same application, and the number that was called will be passed to your answer_url in the to parameter, or in the To header in SIP INVITE for SIP Trunking.

When receiving a call, the Caller ID will be sent in the Answer webhook as the from field, or as From header in the SIP INVITE for SIP trunking.

{
  "from": "442079460000",
  "to": "447700900000",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Vonage attempts to present to you the caller ID of the party calling your Vonage application in international format. However, this can occasionally be incorrectly formatted by the originating network. Vonage passes through the number received from the number supplier. You can learn more about inbound caller ID on our voice features overview page in the Vonage knowledge base.