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

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

API workflow


Features and constraints

Features

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

Constraints


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


Note: 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

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.

Mopinion feedback