Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Developer - Numbers API Reference

The Numbers API lets you manage your numbers and buy new virtual numbers for use with Nexmo's APIs.

Numbers

List owned numbers

Retrieve all the inbound numbers associated with your Nexmo account.

Request

GET  https://rest.nexmo.com/account/numbers
Parameters

The following 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

Response

The following shows example Responses in JSON or XML:

{
  "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"
    },
  ]
}

Keys and Values

The response contains the following keys and values:

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

Search available numbers

Retrieve inbound numbers that are available for a given country.

Request

GET  https://rest.nexmo.com/number/search
Parameters

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

Response

The following shows example Responses in JSON or XML:

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

Keys and Values

The response contains the following keys and values:

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

Buy a number

Request to purchase a specific inbound number.

Request

POST  https://rest.nexmo.com/number/buy
Parameters

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

Response

The following shows example Responses in JSON or XML:

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

Keys and Values

The response contains the following keys and values:

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

Cancel a number

Cancel your subscription for a specific inbound number.

Request

POST  https://rest.nexmo.com/number/cancel
Parameters

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

Response

The following shows example Responses in JSON or XML:

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

Keys and Values

The response contains the following keys and values:

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

Update a number

Change the behaviour of a number that you own

Request

POST  https://rest.nexmo.com/number/update
Parameters

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 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, vxml (VoiceXML) or app No
voiceCallbackValue A URI for your voiceCallbackType or an Application ID
voiceStatusCallback Nexmo sends a request to this webhook endpoint when a call ends. No

Please note, that voiceCallbackValue has to be used together with voiceCallbackType parameter.

Response

The following shows example Responses in JSON or XML:

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