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/en/numbers/overview

Baixar a especificação OpenAPI
Operações disponíveis

List the numbers you own

Retrieve all the inbound numbers associated with your Vonage account.

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Consulta Parâmetros

country
string
Mín.2
Max2
exemploGB
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.

pattern
string

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

search_pattern
integer

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
Deve ser uma das seguintes opções:012
size
integer
Max100
Padrão10

Page size

index
integer
Padrão1

Page index

Respostas
Tipo de conteúdo

OK

count
integer
exemplo1

The total amount of numbers owned by the account

numbers
array

A paginated array of numbers and their details

country
string
Mín.2
Max2
exemploGB

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

msisdn
string
exemplo447700900000

An available inbound virtual number.

moHttpUrl
string(url)
exemplohttps://example.com/webhooks/inbound-sms

The URL of the webhook endpoint that handles inbound messages

type
string
exemplomobile-lvn

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

features
array

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

limitations
array
feature
string
Obrigatório
exemploSMS
Deve ser uma das seguintes opções:MMSSMSVOICE
type
string
Obrigatório
exemploOUTBOUND
Deve ser uma das seguintes opções:INBOUNDOUTBOUND
reach
string
Obrigatório
exemploINTERNATIONAL
Deve ser uma das seguintes opções:DOMESTICINTERNATIONAL
messagesCallbackType
string
exemploapp

The messages webhook type: always app

messagesCallbackValue
string
exemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

An Application ID

voiceCallbackType
string
exemploapp

The voice webhook type: sip, tel, or app

voiceCallbackValue
string
exemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

A SIP URI, telephone number or Application ID

app_id
string
exemplo1ded6eee-e2ec-4d61-8c71-e2b2ece17d1b

The application ID linked to that number

Exemplo Resposta

{
   "count": 1,
   "numbers": [
      {
         "country": "GB",
         "msisdn": "447700900000",
         "moHttpUrl": "https://example.com/webhooks/inbound-sms",
         "type": "mobile-lvn",
         "features": [
            "VOICE",
            "SMS",
            "MMS"
         ],
         "limitations": [
            {
               "feature": "SMS",
               "type": "OUTBOUND",
               "reach": "INTERNATIONAL"
            },
            {
               "feature": "VOICE",
               "type": "OUTBOUND",
               "reach": "DOMESTIC"
            }
         ],
         "messagesCallbackType": "app",
         "messagesCallbackValue": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "voiceCallbackType": "app",
         "voiceCallbackValue": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "app_id": "1ded6eee-e2ec-4d61-8c71-e2b2ece17d1b"
      }
   ]
}

Search available numbers

Retrieve inbound numbers that are available for the specified country.

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Consulta Parâmetros

country
string
Mín.2
Max2
exemploGB

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

Deve ser uma das seguintes opções:landlinemobile-lvnlandline-toll-free
pattern
string

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

search_pattern
integer

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
Deve ser uma das seguintes opções:012
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.

Deve ser uma das seguintes opções:SMSVOICESMS,VOICEMMSSMS,MMSVOICE,MMSSMS,MMS,VOICE
size
integer
Max100
Padrão10

Page size

index
integer
Padrão1

Page index

Respostas
Tipo de conteúdo

OK

count
integer
exemplo1234

The total amount of numbers available in the pool.

numbers
array

A paginated array of available numbers and their details.

country
string
Mín.2
Max2
exemploGB

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

msisdn
string
exemplo447700900000

An available inbound virtual number.

type
string
exemplomobile-lvn

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

initialPrice
string
exemplo1.25

The initial setup fee for this number, in Euros

cost
string
exemplo1.25

The monthly rental cost for this number, in Euros

features
array

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

limitations
array
feature
string
Obrigatório
exemploSMS
Deve ser uma das seguintes opções:MMSSMSVOICE
type
string
Obrigatório
exemploOUTBOUND
Deve ser uma das seguintes opções:INBOUNDOUTBOUND
reach
string
Obrigatório
exemploINTERNATIONAL
Deve ser uma das seguintes opções:DOMESTICINTERNATIONAL

Exemplo Resposta

{
   "count": 1234,
   "numbers": [
      {
         "country": "GB",
         "msisdn": "447700900000",
         "type": "mobile-lvn",
         "initialPrice": "1.25",
         "cost": "1.25",
         "features": [
            "VOICE",
            "SMS",
            "MMS"
         ],
         "limitations": [
            {
               "feature": "SMS",
               "type": "OUTBOUND",
               "reach": "INTERNATIONAL"
            },
            {
               "feature": "VOICE",
               "type": "OUTBOUND",
               "reach": "DOMESTIC"
            }
         ]
      }
   ]
}

Buy a number

Request to purchase a specific inbound number.

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/x-www-form-urlencoded

country
string
Obrigatório
Mín.2
Max2
exemploGB

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

msisdn
string
Obrigatório
exemplo447700900000

An available inbound virtual number.

target_api_key
string
exemplo1a2345b7

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.

Exemplo Solicitação

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
POST /number/buy HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 30

country=GB&msisdn=447700900000

Respostas
Tipo de conteúdo

OK

error-code
string
exemplo200

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

error-code-label
string
exemplosuccess

The status code description

Exemplo Resposta

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

Cancel a number

Cancel your subscription for a specific inbound number.

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/x-www-form-urlencoded

country
string
Obrigatório
Mín.2
Max2
exemploGB

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

msisdn
string
Obrigatório
exemplo447700900000

An available inbound virtual number.

target_api_key
string
exemplo1a2345b7

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.

Exemplo Solicitação

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
POST /number/cancel HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 30

country=GB&msisdn=447700900000

Respostas
Tipo de conteúdo

OK

error-code
string
exemplo200

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

error-code-label
string
exemplosuccess

The status code description

Exemplo Resposta

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

Update a number

Change the behaviour of a number that you own.

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/x-www-form-urlencoded

country
string
Obrigatório
Mín.2
Max2
exemploGB

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

msisdn
string
Obrigatório
exemplo447700900000

An available inbound virtual number.

app_id
string
exemploaaaaaaaa-bbbb-cccc-dddd-0123456789abc

The Application that will handle inbound traffic to this number.

moHttpUrl
string
exemplohttps://example.com/webhooks/inbound-sms

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
exemploinbound

The associated system type for your SMPP client

voiceCallbackType
string
exemplotel

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.

Deve ser uma das seguintes opções:siptelapp
voiceCallbackValue
string
exemplo447700900000

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

voiceStatusCallback
string
exemplohttps://example.com/webhooks/status

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

messagesCallbackType
string
exemploapp

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.

Deve ser uma das seguintes opções:app
messagesCallbackValue
string
exemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

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.

Exemplo Solicitação

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

country=GB&msisdn=447700900000&app_id=aaaaaaaa-bbbb-cccc-dddd-0123456789abc&moHttpUrl=https://example.com/webhooks/inbound-sms&moSmppSysType=inbound&voiceCallbackType=tel&voiceCallbackValue=447700900000&voiceStatusCallback=https://example.com/webhooks/status&messagesCallbackType=app&messagesCallbackValue=aaaaaaaa-bbbb-cccc-dddd-0123456789ab
POST /number/update HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 30

country=GB&msisdn=447700900000

Respostas
Tipo de conteúdo

OK

error-code
string
exemplo200

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

error-code-label
string
exemplosuccess

The status code description

Exemplo Resposta

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