Nexmo Phone Numbers API

API reference on SwaggerHub

Introduction

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

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

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

Getting started

Authentication

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

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.

Result 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 above table are not required but advised to get more tailored results.
  3. Click Send.
  4. Check the response code and message.

Result 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.

Result 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, Nexmo 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 Nexmo 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 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 above table, to your needs.
  3. Click Send.
  4. Check the response code and message.

Result 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