Nexmo

Phone Numbers - Nexmo

Nexmo

Manage, acquire and select your phone numbers programmatically

No more negotiate agreements with regional telco operators

  • Communication

API reference on SwaggerHub API reference on Postman

Introduction

The Phone Numbers API lets you manage your numbers and buy new virtual numbers for use with Nexmo's 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

Setting up your third party accounts

Make sure you have a registered account on the API Store and created an application on the portal, to receive the associated client ID and secret. These are neccessary to request an access token. You will receive these after your app is approved on te API Store.

Authentication

OAuth 2.0

For accessing and/or manipulating the resources, the client application (your application) needs to be granted permission to do so. The OAuth 2.0 standard defines a protocol that allows such third-party authorization through the use of access tokens. Access tokens are central in the protocol: those tokens, in the form of strings, are delivered by an authorization server (our authentication server) and they enable the client application to securely access protected data on behalf of the resource owner (the end-user). We use Client Credentials Grant which means the application makes the request to the authentication service by sending authorization credentials and the service responds with an access token among other useful information.

Get Access Token

Copy your app's credentials (Consumer Key and Consumer Secret) to be used in the Authentication requests below.

Authentication in SwaggerHub

  1. Upon loading completed within SwaggerHub, look top right for the Authorize button and click it.
  2. In the form, fill in client_id and client_secret fields, using your app's credentials.
  3. Click Authorize.
  4. Now you are authorized to issue the requests provided.

Authentication in Postman

  1. Select Get Access Token from the collection.
  2. Make sure the right Environment corresponding to the API is selected.
  3. Edit the environment variables client_id and client_secret, using your app's credentials.
  4. Check the response code and message.
  5. Press the Send button to get the access token.
  6. Now you are authorized to issue the other requests in the collection.

The authorization 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": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

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

API versions

Version   Description
1.0   Initial version