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
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
You can find your API key in the developer dashboard
You can find your API secret in the developer dashboard
The Application that you want to return the numbers for.
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.
The two character country code in ISO 3166-1 alpha-2 format
The number pattern you want to search for. Use in conjunction with search_pattern
.
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
0
, 1
or 2
Page size
Page index
The total amount of numbers owned by the account
A paginated array of numbers and their details
The two character country code in ISO 3166-1 alpha-2 format
An available inbound virtual number.
The URL of the webhook endpoint that handles inbound messages
The type of number: landline
, landline-toll-free
or mobile-lvn
The capabilities of the number: SMS
or VOICE
or SMS,VOICE
or SMS,MMS
or VOICE,MMS
or SMS,MMS,VOICE
The messages webhook type: always app
An Application ID
The voice webhook type: sip
, tel
, or app
A SIP URI, telephone number or Application ID
The total amount of numbers owned by the account
A paginated array of numbers and their details
The two character country code in ISO 3166-1 alpha-2 format
An available inbound virtual number.
The URL of the webhook endpoint that handles inbound messages
The type of number: landline
, landline-toll-free
or mobile-lvn
The capabilities of the number: SMS
or VOICE
or SMS,VOICE
or SMS,MMS
or VOICE,MMS
or SMS,MMS,VOICE
The messages webhook type: always app
An Application ID
The voice webhook type: sip
, tel
, or app
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",
"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>
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
You can find your API key in the developer dashboard
You can find your API secret in the developer dashboard
The two character country code to filter on (in ISO 3166-1 alpha-2 format)
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
The number pattern you want to search for. Use in conjunction with search_pattern
.
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
0
, 1
or 2
Available features are SMS
, VOICE
and MMS
. To look for numbers that support multiple features, use a comma-separated value: SMS,MMS,VOICE
.
SMS
, VOICE
, SMS,VOICE
, MMS
, SMS,MMS
, VOICE,MMS
or SMS,MMS,VOICE
Page size
Page index
The total amount of numbers available in the pool.
A paginated array of available numbers and their details.
The two character country code in ISO 3166-1 alpha-2 format
An available inbound virtual number.
The type of number: landline
, landline-toll-free
or mobile-lvn
The monthly rental cost for this number, in Euros
The capabilities of the number: SMS
or VOICE
or SMS,VOICE
or SMS,MMS
or VOICE,MMS
or SMS,MMS,VOICE
The total amount of numbers available in the pool.
A paginated array of available numbers and their details.
The two character country code in ISO 3166-1 alpha-2 format
An available inbound virtual number.
The type of number: landline
, landline-toll-free
or mobile-lvn
The monthly rental cost for this number, in Euros
The capabilities of the number: SMS
or VOICE
or SMS,VOICE
or SMS,MMS
or VOICE,MMS
or SMS,MMS,VOICE
{
"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>
Request to purchase a specific inbound number.
POST
https://rest.nexmo.com/number/buy
Host
https://rest.nexmo.com
POST
/number/buy
You can find your API key in the developer dashboard
You can find your API secret in the developer dashboard
Number details
The two character country code in ISO 3166-1 alpha-2 format
An available inbound virtual number.
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.
The status code of the response. 200
indicates a successful request.
The status code description
The status code of the response. 200
indicates a successful request.
The status code description
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
{
"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 your subscription for a specific inbound number.
POST
https://rest.nexmo.com/number/cancel
Host
https://rest.nexmo.com
POST
/number/cancel
You can find your API key in the developer dashboard
You can find your API secret in the developer dashboard
Number details
The two character country code in ISO 3166-1 alpha-2 format
An available inbound virtual number.
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.
The status code of the response. 200
indicates a successful request.
The status code description
The status code of the response. 200
indicates a successful request.
The status code description
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
{
"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>
Change the behaviour of a number that you own.
POST
https://rest.nexmo.com/number/update
Host
https://rest.nexmo.com
POST
/number/update
You can find your API key in the developer dashboard
You can find your API secret in the developer dashboard
Number details
The two character country code in ISO 3166-1 alpha-2 format
An available inbound virtual number.
The Application that will handle inbound traffic to this number.
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.
The associated system type for your SMPP client
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.
sip
, tel
or app
A SIP URI or telephone number. Must be used with the voiceCallbackType
parameter.
A webhook URI for Vonage to send a request to when a call ends
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.
app
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.
The status code of the response. 200
indicates a successful request.
The status code description
The status code of the response. 200
indicates a successful request.
The status code description
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
{
"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>