Introduction

Nexmo is now called Vonage, but there are still references to Nexmo in our URLs, code snippets and message templates.

The Phone Numbers API lets you get, select and manage programmable virtual phone numbers to use with Vonage's other APIs.

API specification

Test the API on SwaggerHub

Base URL

https://api-prd.kpn.com/communication/nexmo/phone-numbers

Conceptual model

Definitions

Virtual number

A virtual number is a telephone number without a directly associated telephone line. Usually, these numbers are programmed to forward incoming calls to one of the pre-set telephone numbers, chosen by the client: fixed, mobile or VoIP.

SIP

The Session Initiation Protocol (SIP) is used for signaling and controlling multimedia communication sessions in applications of Internet telephony for voice and video calls, in private IP telephone systems, in instant messaging over Internet Protocol (IP) networks as well as mobile phone calling over LTE (VoLTE).

API workflow

Features and constraints

Features

• Administer your number through this API.
• Instant provisioning through code.
• Search for available numbers.

Constraints

• To check which countries are supported, please check the Vonage help page.

Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

• Authenticate to an API using cURL.
• Authenticate to an API on Swaggerhub.
• Import Open API Specifications (OAS), also called Swagger files into Postman.

How to...

List owned numbers

Retrieve all the inbound numbers associated with your account.

The following table shows the parameters you use in the request:

Parameter	Description	Required
index	Page index Default: 1	No
size	Page size Max: 100 Default: 10	No
pattern	A matching pattern	No
search_pattern	Strategy for matching pattern. Expected values: 0 (starts with, default), 1(anywhere), 2 (ends with).	No

SwaggerHub:

1. Select GET /account/numbers.
2. Click Try it out'.
3. Edit the parameters by filling out Index, size, pattern and search_pattern.
4. Click 'Execute'.
5. Check the response code and message.

Postman:

1. Select (GET) List owned numbers.
2. Click the Paramssection of the request and provide values for the following keys: Index, size, pattern and search_pattern.
3. Click 'Send'.
4. Check the response code and message.

^^Response example^^
{
  "count": 1,
  "numbers": [
    {
      "country": "GB",
      "msisdn": "447700900000",
      "moHttpUrl": "https://example.com/mo",
      "type": "mobile-lvn",
      "features": [
        "VOICE",
        "SMS"
      ],
      "voiceCallbackType": "app",
      "voiceCallbackValue": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    },
  ]
}

The response contains the following keys and values:

Key	Value
count	The total amount of numbers owned by account.
numbers	A paginated array of numbers and their details.

Search available numbers

Retrieve inbound numbers that are available for a given country.

The following table shows the parameters you use in the request:

Parameter	Description	Required
country	The two-character country code in ISO 3166-1 alpha-2 format.	Yes
pattern	A number pattern to search for.	No
search_pattern	Strategy for matching pattern. Expected values: 0 (starts with, default), 1(anywhere), 2 (ends with).	No
type	The type of number to search for. Accepted values: landline, landline-toll-free and mobile-lvn.	No
features	Available features are SMS and VOICE. For both features, use a comma-separated value SMS,VOICE.	No
size	Page size Max: 100 Default: 10	No
index	Page index Default: 1	No

SwaggerHub:

1. Select GET /number/search.
2. Click 'Try it out'.
3. Edit the parameters by filling out country. Other parameters are not required but advised to get more tailored results.
4. Click 'Execute'.
5. Check the response code and message.

Postman:

1. Select (GET) Search available numbers.
2. Click the Paramssection of the request and provide values for country. Other parameters from the above table are not required but advised to get more tailored results.
3. Click 'Send'.
4. Check the response code and message.

^^Response example^^
{
  "count": 1234,
  "numbers": [
    {
      "country": "GB",
      "msisdn": "447700900000",
      "cost": "1.25",
      "type": "mobile-lvn",
      "features": [
        "VOICE",
        "SMS",
      ]
    },
    ...
  ]
}

The response contains the following keys and values:

Key	Value
count	The total amount of numbers available in the pool.
numbers	A paginated array of available numbers and their details.

Buy a number

Request to purchase a specific inbound number.

The following table shows the parameters you use in the request:

Parameter	Description	Required
country	The two-character country code in ISO 3166-1 alpha-2 format.	Yes
msisdn	An available inbound virtual number. For example, 447700900000.	Yes

SwaggerHub:

1. Select POST /number/buy.
2. Click 'Try it out'.
3. Edit the parameters by filling out country and msisdn.
4. Click 'Execute'.
5. Check the response code and message.

Postman:

1. Select (POST) Buy a number.
2. Click the Bodysection of the request and provide values for country and msisdn.
3. Click 'Send'.
4. Check the response code and message.

^^Result example^^
{
  "error-code":"200",
  "error-code-label":"success"
}

Cancel a number

Cancel your subscription for a specific inbound number.

The following shows the parameters you use in the request:

Parameter	Description	Required
country	The two-character country code in ISO 3166-1 alpha-2 format.	Yes
msisdn	One of your inbound numbers. For example, 447700900000.	Yes

SwaggerHub:

1. Select POST /number/cancel.
2. Click 'Try it out'.
3. Edit the parameters by filling out country and msisdn.
4. Click 'Execute'.
5. Check the response code and message.

Postman:

1. Select (POST) Cancel a number.
2. Click the Bodysection of the request and provide values for country and msisdn.
3. Click 'Send'.
4. Check the response code and message.

^^Response example^^
{
  "error-code":"200",
  "error-code-label":"success"
}

Update a number

Change the behavior of a number that you own.

The following shows the parameters you use in the request:

Parameter	Description	Required
country	The two character country code in ISO 3166-1 alpha-2 format.	Yes
msisdn	An available inbound virtual number. For example, 447700900000.	Yes
moHttpUrl	An URL-encoded URI to the webhook endpoint that handles inbound messages. Your webhook endpoint must be active before you make this request, Vonage makes a GET request to your endpoint and checks that it returns a 200 OK response. Set to empty string to clear.	No
moSmppSysType	The associated system type for your SMPP client. For example inbound.	No
voiceCallbackType	The voice webhook type. Possible values are sip, tel, or app	No
voiceCallbackValue	A SIP URI, telephone number or Application ID	No
voiceStatusCallback	A webhook URI for Vonage to send a request to when a call ends.	No

voiceCallbackValue has to be used together with the voiceCallbackType parameter.

SwaggerHub:

1. Select POST /number/update.
2. Click 'Try it out'.
3. Edit the parameters by filling out country and msisdn. Also edit the other parameters, as mentioned in the above table, to your needs.
4. Click 'Execute'.
5. Check the response code and message.

Postman:

1. Select (POST) Update a number.
2. Click the Bodysection of the request and provide values for country and msisdn. Also edit the other parameters in the body, as mentioned in the above table, to your needs.
3. Click 'Send'.
4. Check the response code and message.

^^Response example^^
{
  "error-code":"200",
  "error-code-label":"success"
}

Return codes

HTTP response headers

The following tables display the standard response headers that are returned with each API response: