Numbers API

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

Download OAS 3 Definition

Improve this specification

Available Operations:

get List the numbers you own
get Search available numbers
post Buy a number
post Cancel a number
post Update a number

List the numbers you own

Retrieve all the inbound numbers associated with your Vonage account.

GET


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

Host


        https://rest.nexmo.com

GET


        /account/numbers

Query Parameter

api_key

apiKey

You can find your API key in the developer dashboard

api_secret

apiKey

You can find your API secret in the developer dashboard

application_id

string

The Application that you want to return the numbers for.

has_application

boolean

Set this optional field to true to restrict your results to numbers associated with an Application (any Application). Set to false to find all numbers not associated with any Application. Omit the field to avoid filtering on whether or not the number is assigned to an Application.

country

string

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

pattern

string

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

search_pattern

integer | Default: 0

The strategy you want to use for matching:

0 - Search for numbers that start with pattern (Note: all numbers are in E.164 format, so the starting pattern includes the country code, such as 1 for USA)
1 - Search for numbers that contain pattern
2 - Search for numbers that end with pattern

Must be one of: 0, 1 or 2

size

integer | Default: 10

Page size

index

integer | Default: 1

Page index

Responses

200 OK

count

integer

The total amount of numbers owned by the account

numbers

array of objects

A paginated array of numbers and their details

string

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

string

An available inbound virtual number.

string

The URL of the webhook endpoint that handles inbound messages

string

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

array of strings

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

string

The messages webhook type: always app

string

An Application ID

string

The voice webhook type: sip, tel, or app

string

A SIP URI, telephone number or Application ID

count

integer

The total amount of numbers owned by the account

numbers

array of objects

A paginated array of numbers and their details

string

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

string

An available inbound virtual number.

string

The URL of the webhook endpoint that handles inbound messages

string

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

array of strings

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

string

The messages webhook type: always app

string

An Application ID

string

The voice webhook type: sip, tel, or app

string

A SIP URI, telephone number or Application ID

Example Responses

200 401

{
  "count": 1,
  "numbers": [
    {
      "country": "GB",
      "msisdn": "447700900000",
      "moHttpUrl": "https://example.com/webhooks/inbound-sms",
      "type": "mobile-lvn",
      "features": [
        "VOICE",
        "SMS",
        "MMS"
      ],
      "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>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>
        <feature>MMS</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>

{
  "error-code": "401",
  "error-code-label": "authentication failed"
}

<?xml version="1.0" encoding="UTF-8"?>
<inbound-numbers>
  <error-code>401</error-code>
  <error-code-label>authentication failed</error-code-label>
</inbound-numbers>

Search available numbers

Retrieve inbound numbers that are available for the specified country.

GET


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

Host


        https://rest.nexmo.com

GET


        /number/search

Query Parameter

api_key

apiKey

You can find your API key in the developer dashboard

api_secret

apiKey

You can find your API secret in the developer dashboard

country

string | Required

The two character country code to filter on (in ISO 3166-1 alpha-2 format)

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

pattern

string

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

search_pattern

integer | Default: 0

The strategy you want to use for matching:

0 - Search for numbers that start with pattern (Note: all numbers are in E.164 format, so the starting pattern includes the country code, such as 1 for USA)
1 - Search for numbers that contain pattern
2 - Search for numbers that end with pattern

Must be one of: 0, 1 or 2

features

string

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

Must be one of: SMS, VOICE, SMS,VOICE, MMS, SMS,MMS, VOICE,MMS or SMS,MMS,VOICE

size

integer | Default: 10

Page size

index

integer | Default: 1

Page index

Responses

200 OK

count

integer

The total amount of numbers available in the pool.

numbers

array of objects

A paginated array of available numbers and their details.

string

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

string

An available inbound virtual number.

string

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

string

The monthly rental cost for this number, in Euros

array of strings

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

count

integer

The total amount of numbers available in the pool.

numbers

array of objects

A paginated array of available numbers and their details.

string

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

string

An available inbound virtual number.

string

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

string

The monthly rental cost for this number, in Euros

array of strings

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

Example Responses

200 401

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

<?xml version="1.0" encoding="UTF-8"?>
<inbound-numbers>
  <count>1234</count>
  <numbers>
    <number>
      <country>GB</country>
      <msisdn>447700900000</msisdn>
      <type>mobile-lvn</type>
      <cost>1.25</cost>
      <features>
        <feature>VOICE</feature>
        <feature>SMS</feature>
        <feature>MMS</feature>
      </features>
    </number>
  </numbers>
</inbound-numbers>

{
  "error-code": "401",
  "error-code-label": "authentication failed"
}

<?xml version="1.0" encoding="UTF-8"?>
<inbound-numbers>
  <error-code>401</error-code>
  <error-code-label>authentication failed</error-code-label>
</inbound-numbers>

Buy a number

Request to purchase a specific inbound number.

POST


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

Host


        https://rest.nexmo.com

POST


        /number/buy

Query Parameter

api_key

apiKey

You can find your API key in the developer dashboard

api_secret

apiKey

You can find your API secret in the developer dashboard

Request body application/x-www-form-urlencoded

Number details

country

string | Required | Min: 2 | Max: 2

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

msisdn

string | Required

An available inbound virtual number.

target_api_key

string

If you’d like to perform an action on a subaccount, provide the api_key of that account here. If you’d like to perform an action on your own account, you do not need to provide this field.

Responses

200 OK

error-code

string

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

error-code-label

string

The status code description

error-code

string

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

error-code-label

string

The status code description

Example Request

POST /number/buy HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 30

country=GB&msisdn=447700900000

POST /number/buy HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 54

country=GB&msisdn=447700900000&target_api_key=1a2345b7

Example Responses

200 401 420

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error-code>200</error-code>
  <error-code-label>success</error-code-label>
</response>

{
  "error-code": "401",
  "error-code-label": "authentication failed"
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error-code>401</error-code>
  <error-code-label>authentication failed</error-code-label>
</response>

{
  "error-code": "420",
  "error-code-label": "Numbers from this country can be requested from the Dashboard (https://dashboard.nexmo.com/buy-numbers) as they require a valid local address to be provided before being purchased."
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error-code>420</error-code>
  <error-code-label>Numbers from this country can be requested from the Dashboard (https://dashboard.nexmo.com/buy-numbers) as they require a valid local address to be provided before being purchased.</error-code-label>
</response>

Cancel a number

Cancel your subscription for a specific inbound number.

POST


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

Host


        https://rest.nexmo.com

POST


        /number/cancel

Query Parameter

api_key

apiKey

You can find your API key in the developer dashboard

api_secret

apiKey

You can find your API secret in the developer dashboard

Request body application/x-www-form-urlencoded

Number details

country

string | Required | Min: 2 | Max: 2

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

msisdn

string | Required

An available inbound virtual number.

target_api_key

string

If you’d like to perform an action on a subaccount, provide the api_key of that account here. If you’d like to perform an action on your own account, you do not need to provide this field.

Responses

200 OK

error-code

string

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

error-code-label

string

The status code description

error-code

string

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

error-code-label

string

The status code description

Example Request

POST /number/cancel HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 30

country=GB&msisdn=447700900000

POST /number/cancel HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 54

country=GB&msisdn=447700900000&target_api_key=1a2345b7

Example Responses

200 401

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error-code>200</error-code>
  <error-code-label>success</error-code-label>
</response>

{
  "error-code": "401",
  "error-code-label": "authentication failed"
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error-code>401</error-code>
  <error-code-label>authentication failed</error-code-label>
</response>

Update a number

Change the behaviour of a number that you own.

POST


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

Host


        https://rest.nexmo.com

POST


        /number/update

Query Parameter

api_key

apiKey

You can find your API key in the developer dashboard

api_secret

apiKey

You can find your API secret in the developer dashboard

Request body application/x-www-form-urlencoded

Number details

country

string | Required | Min: 2 | Max: 2

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

msisdn

string | Required

An available inbound virtual number.

app_id

string

The Application that will handle inbound traffic to this number.

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

moSmppSysType

string

The associated system type for your SMPP client

voiceCallbackType

string

Specify whether inbound voice calls on your number are forwarded to a SIP or a telephone number. This must be used with the voiceCallbackValue parameter. If set, sip or tel are prioritized over the Voice capability in your Application.

Note: The app value is deprecated and will be removed in future.

Must be one of: sip, tel or app

voiceCallbackValue

string

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

voiceStatusCallback

string

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

messagesCallbackType

string | DEPRECATED : This field has been deprecated.

DEPRECATED - We recommend that you use app_id instead.

Specifies the Messages webhook type (always app) associated with this number and must be used with the messagesCallbackValue parameter.

Must be one of: app

messagesCallbackValue

string | DEPRECATED : This field has been deprecated.

DEPRECATED - We recommend that you use app_id instead.

Specifies the Application ID of your Messages application. It must be used with the messagesCallbackType parameter.

Responses

200 OK

error-code

string

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

error-code-label

string

The status code description

error-code

string

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

error-code-label

string

The status code description

Example Request

POST /number/update HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 30

country=GB&msisdn=447700900000

POST /number/update HTTP/1.1
Host: rest.nexmo.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 362

country=GB&msisdn=447700900000&app_id=aaaaaaaa-bbbb-cccc-dddd-0123456789abc&moHttpUrl=https%3A%2F%2Fexample.com%2Fwebhooks%2Finbound-sms&moSmppSysType=inbound&voiceCallbackType=tel&voiceCallbackValue=447700900000&voiceStatusCallback=https%3A%2F%2Fexample.com%2Fwebhooks%2Fstatus&messagesCallbackType=app&messagesCallbackValue=aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Example Responses

200 401

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error-code>200</error-code>
  <error-code-label>success</error-code-label>
</response>

{
  "error-code": "401",
  "error-code-label": "authentication failed"
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error-code>401</error-code>
  <error-code-label>authentication failed</error-code-label>
</response>