Numbers API

The Numbers API enables you to manage your existing numbers and buy new virtual numbers for use with Nexmo's APIs. Further information is here: https://developer.nexmo.com/numbers/overview

List the numbers you own

Retrieve all the inbound numbers associated with your Nexmo account.

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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in the developer dashboard

abc123 None
api_secret
apiKey

You can find your API key in the developer dashboard

abc123 None
index
integer

Page index

1 1
size
integer

Page size

10 10
pattern
string

The number pattern you want to search for. Use in conjunction with search_pattern.

12345 None
search_pattern
integer

The strategy you want to use for matching:

  • 0 - Search for numbers that start with pattern
  • 1 - Search for numbers that contain pattern
  • 2 - Search for numbers that end with pattern

Must be one of: 0, 1 or 2
1 0

View response field descriptions

Response Fields

Field Description
count

The total amount of numbers owned by the account

numbers
array of objects

A paginated array of numbers and their details

Field Description
country

The two character country code in ISO 3166-1 alpha-2 format

msisdn

An available inbound virtual number.

moHttpUrl

The URL of the webhook endpoint that handles inbound messages

type

The type of number: landline, landline-toll-free or mobile-lvn

features
array of strings

The capabilities of the number: SMS or VOICE or SMS,VOICE

messagesCallbackType

The messages webhook type: always app

messagesCallbackValue

A Nexmo Application ID

voiceCallbackType

The voice webhook type: sip, tel, or app

voiceCallbackValue

A SIP URI, telephone number or Application ID

Field Description
count

The total amount of numbers owned by the account

numbers
array of objects

A paginated array of numbers and their details

Field Description
country

The two character country code in ISO 3166-1 alpha-2 format

msisdn

An available inbound virtual number.

moHttpUrl

The URL of the webhook endpoint that handles inbound messages

type

The type of number: landline, landline-toll-free or mobile-lvn

features
array of strings

The capabilities of the number: SMS or VOICE or SMS,VOICE

messagesCallbackType

The messages webhook type: always app

messagesCallbackValue

A Nexmo Application ID

voiceCallbackType

The voice webhook type: sip, tel, or app

voiceCallbackValue

A SIP URI, telephone number or Application ID

{
  "count": 1,
  "numbers": [
    {
      "country": "GB",
      "msisdn": "447700900000",
      "moHttpUrl": "https://example.com/webhooks/inbound-sms",
      "type": "mobile-lvn",
      "features": [
        "VOICE",
        "SMS"
      ],
      "messagesCallbackType": "app",
      "messagesCallbackValue": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "voiceCallbackType": "app",
      "voiceCallbackValue": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count>1</count>
  <numbers>
    <number>
      <country>GB</country>
      <msisdn>447700900000</msisdn>
      <moHttpUrl>https://example.com/webhooks/inbound-sms</moHttpUrl>
      <type>mobile-lvn</type>
      <features>
        <feature>VOICE</feature>
        <feature>SMS</feature>
      </features>
      <messagesCallbackType>app</messagesCallbackType>
      <messagesCallbackValue>
        aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      </messagesCallbackValue>
      <voiceCallbackType>app</voiceCallbackType>
      <voiceCallbackValue>
        aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      </voiceCallbackValue>
    </number>
  </numbers>
</hash>
No content

Search available numbers

Retrieve inbound numbers that are available for the specified country.

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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in the developer dashboard

abc123 None
api_secret
apiKey

You can find your API key in the developer dashboard

abc123 None
country
Required | string

The two character country code in ISO 3166-1 alpha-2 format

GB None
type
string

Set this parameter to filter the type of number, such as mobile or landline


Must be one of: landline, mobile-lvn or landline-toll-free
mobile-lvn None
pattern
string

The number pattern you want to search for. Use in conjunction with search_pattern.

12345 None
search_pattern
integer

The strategy you want to use for matching:

  • 0 - Search for numbers that start with pattern
  • 1 - Search for numbers that contain pattern
  • 2 - Search for numbers that end with pattern

Must be one of: 0, 1 or 2
1 0
features
string

Available features are SMS and VOICE. To look for numbers that support both, use a comma-separated value: SMS,VOICE.


Must be one of: SMS, VOICE or SMS,VOICE
SMS None
size
integer

Page size

10 10
index
integer

Page index

1 1

View response field descriptions

Response Fields

Field Description
count

The total amount of numbers available in the pool.

numbers
array of objects

A paginated array of available numbers and their details.

Field Description
country

The two character country code in ISO 3166-1 alpha-2 format

msisdn

An available inbound virtual number.

moHttpUrl

The URL of the webhook endpoint that handles inbound messages

type

The type of number: landline, landline-toll-free or mobile-lvn

features
array of strings

The capabilities of the number: SMS or VOICE or SMS,VOICE

messagesCallbackType

The messages webhook type: always app

messagesCallbackValue

A Nexmo Application ID

voiceCallbackType

The voice webhook type: sip, tel, or app

voiceCallbackValue

A SIP URI, telephone number or Application ID

Field Description
count

The total amount of numbers available in the pool.

numbers
array of objects

A paginated array of available numbers and their details.

Field Description
country

The two character country code in ISO 3166-1 alpha-2 format

msisdn

An available inbound virtual number.

moHttpUrl

The URL of the webhook endpoint that handles inbound messages

type

The type of number: landline, landline-toll-free or mobile-lvn

features
array of strings

The capabilities of the number: SMS or VOICE or SMS,VOICE

messagesCallbackType

The messages webhook type: always app

messagesCallbackValue

A Nexmo Application ID

voiceCallbackType

The voice webhook type: sip, tel, or app

voiceCallbackValue

A SIP URI, telephone number or Application ID

{
  "count": 1234,
  "numbers": [
    {
      "country": "GB",
      "msisdn": "447700900000",
      "moHttpUrl": "https://example.com/webhooks/inbound-sms",
      "type": "mobile-lvn",
      "features": [
        "VOICE",
        "SMS"
      ],
      "messagesCallbackType": "app",
      "messagesCallbackValue": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "voiceCallbackType": "app",
      "voiceCallbackValue": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<inbound-numbers>
  <count>1234</count>
  <numbers>
    <number>
      <country>GB</country>
      <msisdn>447700900000</msisdn>
      <moHttpUrl>https://example.com/webhooks/inbound-sms</moHttpUrl>
      <type>mobile-lvn</type>
      <features>
        <feature>VOICE</feature>
        <feature>SMS</feature>
      </features>
      <messagesCallbackType>app</messagesCallbackType>
      <messagesCallbackValue>
        aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      </messagesCallbackValue>
      <voiceCallbackType>app</voiceCallbackType>
      <voiceCallbackValue>
        aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      </voiceCallbackValue>
    </number>
  </numbers>
</inbound-numbers>
No content

Buy a number

Request to purchase a specific inbound number.

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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in the developer dashboard

abc123 None
api_secret
apiKey

You can find your API key in the developer dashboard

abc123 None

Request body application/x-www-form-urlencoded

Key Description Example Default
country
Required | string

The two character country code in ISO 3166-1 alpha-2 format

GB None
msisdn
Required | string

An available inbound virtual number.

447700900000 None

View response field descriptions

Response Fields

Field Description
error-code

The status code of the response. 200 indicates a successful request.

error-code-label

The status code description

Field Description
error-code

The status code of the response. 200 indicates a successful request.

error-code-label

The status code description

{
  "error-code": 200,
  "error-code-label": "success"
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <error-code>200</error-code>
  <error-code-label>success</error-code-label>
</hash>
No content

Cancel a number

Cancel your subscription for a specific inbound number.

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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in the developer dashboard

abc123 None
api_secret
apiKey

You can find your API key in the developer dashboard

abc123 None

Request body application/x-www-form-urlencoded

Key Description Example Default
country
Required | string

The two character country code in ISO 3166-1 alpha-2 format

GB None
msisdn
Required | string

An available inbound virtual number.

447700900000 None

View response field descriptions

Response Fields

Field Description
error-code

The status code of the response. 200 indicates a successful request.

error-code-label

The status code description

Field Description
error-code

The status code of the response. 200 indicates a successful request.

error-code-label

The status code description

{
  "error-code": 200,
  "error-code-label": "success"
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <error-code>200</error-code>
  <error-code-label>success</error-code-label>
</hash>
No content

Update a number

Change the behaviour of a number that you own.

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

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in the developer dashboard

abc123 None
api_secret
apiKey

You can find your API key in the developer dashboard

abc123 None

Request body application/x-www-form-urlencoded

Key Description Example Default
country
Required | string

The two character country code in ISO 3166-1 alpha-2 format

GB None
msisdn
Required | string

An available inbound virtual number.

447700900000 None
moHttpUrl
string

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 the endpoint and checks that it returns a 200 OK response. Set this parameter's value to an empty string to remove the webhook.

https://example.com/webhooks/inbound-sms None
moSmppSysType
string

The associated system type for your SMPP client

inbound None
messagesCallbackType
string

The SMS webhook type (always app). Must be used with the messagesCallbackValue parameter.


Must be one of: app
app None
messagesCallbackValue
string

A Nexmo Application ID. Must be used with the messagesCallbackType parameter.

aaaaaaaa-bbbb-cccc-dddd-0123456789ab None
voiceCallbackType
string

The voice webhook type. Must be used with the voiceCallbackValue parameter.


Must be one of: sip, tel or app
sip None
voiceCallbackValue
string

A SIP URI, telephone number or Application ID. Must be used with the voiceCallbackType parameter.

447700900000 None
voiceStatusCallback
string

A webhook URI for Nexmo to send a request to when a call ends

https://example.com/webhooks/status None

View response field descriptions

Response Fields

Field Description
error-code

The status code of the response. 200 indicates a successful request.

error-code-label

The status code description

Field Description
error-code

The status code of the response. 200 indicates a successful request.

error-code-label

The status code description

{
  "error-code": 200,
  "error-code-label": "success"
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <error-code>200</error-code>
  <error-code-label>success</error-code-label>
</hash>
No content