Phone Numbers Documentation

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:

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
      
        Code copied
        
            
      

{
  "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:

Search available numbers

Retrieve inbound numbers that are available for a given country.

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

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
      
        Code copied
        
            
      

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

The response contains the following keys and values:

Buy a number

Request to purchase a specific inbound number.

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

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
      
        Code copied
        
            
      

{
  "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:

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
      
        Code copied
        
            
      

{
  "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:

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
      
        Code copied
        
            
      

{
  "error-code":"200",
  "error-code-label":"success"
}