Numbers API
The Numbers API enables you to manage your existing numbers and buy new virtual numbers for use with the Vonage APIs
COMMUNITYAPI KEY0 INSTALLS
OpenAPI Specificationv3.0
{
"openapi": "3.0.0",
"servers": [
{
"url": "https://rest.nexmo.com"
}
],
"info": {
"contact": {
"email": "devrel@vonage.com",
"name": "Vonage DevRel",
"url": "https://developer.nexmo.com"
},
"description": "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>",
"license": {
"name": "The MIT License (MIT)",
"url": "https://opensource.org/licenses/MIT"
},
"termsOfService": "https://www.nexmo.com/terms-of-use",
"title": "Numbers API",
"version": "1.0.20",
"x-apiClientRegistration": "https://dashboard.nexmo.com/sign-up",
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_www.vonage.com_content_dam_vonage_us-en_api_illustrations_Mobile_APIs_Services.svg"
},
"x-origin": [
{
"format": "openapi",
"url": "https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/numbers.yml",
"version": "3.0"
}
],
"x-providerName": "nexmo.com",
"x-serviceName": "numbers"
},
"externalDocs": {
"description": "Numbers product documentation on the Vonage Developer Portal",
"url": "https://developer.nexmo.com/numbers/overview"
},
"security": [
{
"apiKey": [],
"apiSecret": []
}
],
"paths": {
"/account/numbers": {
"get": {
"description": "Retrieve all the inbound numbers associated with your Vonage account.",
"operationId": "getOwnedNumbers",
"parameters": [
{
"$ref": "#/components/parameters/application_id"
},
{
"$ref": "#/components/parameters/has_application"
},
{
"in": "query",
"name": "country",
"required": false,
"schema": {
"$ref": "#/components/schemas/country"
}
},
{
"$ref": "#/components/parameters/pattern"
},
{
"$ref": "#/components/parameters/search_pattern"
},
{
"$ref": "#/components/parameters/size"
},
{
"$ref": "#/components/parameters/index"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inbound-numbers"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/inbound-numbers"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/account-unauthorized"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/account-unauthorized"
}
}
},
"description": "Unauthorized"
}
},
"summary": "List the numbers you own"
}
},
"/number/buy": {
"post": {
"description": "Request to purchase a specific inbound number.",
"operationId": "buyANumber",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/number-details"
}
}
},
"description": "Number details",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/response"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/response"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/unauthorized"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/unauthorized"
}
}
},
"description": "Unauthorized"
},
"420": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/response420"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/response420"
}
}
},
"description": "Action failed"
}
},
"summary": "Buy a number"
}
},
"/number/cancel": {
"post": {
"description": "Cancel your subscription for a specific inbound number.",
"operationId": "cancelANumber",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/number-details"
}
}
},
"description": "Number details",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/response"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/response"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/unauthorized"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/unauthorized"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Cancel a number"
}
},
"/number/search": {
"get": {
"description": "Retrieve inbound numbers that are available for the specified country.",
"operationId": "getAvailableNumbers",
"parameters": [
{
"$ref": "#/components/parameters/country"
},
{
"$ref": "#/components/parameters/type"
},
{
"$ref": "#/components/parameters/pattern"
},
{
"$ref": "#/components/parameters/search_pattern"
},
{
"description": "Available features are `SMS`, `VOICE` and `MMS`. To look for numbers that support multiple features, use a comma-separated value: `SMS,MMS,VOICE`.",
"example": "SMS",
"in": "query",
"name": "features",
"required": false,
"schema": {
"enum": [
"SMS",
"VOICE",
"SMS,VOICE",
"MMS",
"SMS,MMS",
"VOICE,MMS",
"SMS,MMS,VOICE"
],
"type": "string"
}
},
{
"$ref": "#/components/parameters/size"
},
{
"$ref": "#/components/parameters/index"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/available-numbers"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/available-numbers"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/account-unauthorized"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/account-unauthorized"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Search available numbers"
}
},
"/number/update": {
"post": {
"description": "Change the behaviour of a number that you own.",
"operationId": "updateANumber",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/number-details-update"
}
}
},
"description": "Number details",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/response"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/response"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/unauthorized"
}
},
"text/xml": {
"schema": {
"$ref": "#/components/schemas/unauthorized"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Update a number"
}
}
},
"components": {
"parameters": {
"application_id": {
"description": "The Application that you want to return the numbers for.",
"example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"in": "query",
"name": "application_id",
"required": false,
"schema": {
"type": "string"
}
},
"country": {
"description": "The two character country code to filter on (in ISO 3166-1 alpha-2 format)",
"in": "query",
"name": "country",
"required": true,
"schema": {
"$ref": "#/components/schemas/country"
}
},
"has_application": {
"description": "Set this optional field to `true` to restrict your results to numbers\nassociated with an Application (any Application). Set to `false` to\nfind all numbers not associated with any Application. Omit the field\nto avoid filtering on whether or not the number is assigned to an\nApplication.\n",
"example": false,
"in": "query",
"name": "has_application",
"required": false,
"schema": {
"type": "boolean"
}
},
"index": {
"description": "Page index",
"example": 1,
"in": "query",
"name": "index",
"required": false,
"schema": {
"default": 1,
"type": "integer"
}
},
"msisdn": {
"description": "The inbound number you want to cancel, in [E.164 international format](/concepts/guides/glossary#e-164-format)",
"example": "447700900000",
"in": "query",
"name": "msisdn",
"required": true,
"schema": {
"type": "string"
}
},
"pattern": {
"description": "The number pattern you want to search for. Use in conjunction with `search_pattern`.",
"example": "12345",
"in": "query",
"name": "pattern",
"required": false,
"schema": {
"type": "string"
}
},
"search_pattern": {
"description": "The strategy you want to use for matching:\n\n\n* `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)\n* `1` - Search for numbers that contain `pattern`\n* `2` - Search for numbers that end with `pattern`\n",
"example": 1,
"in": "query",
"name": "search_pattern",
"required": false,
"schema": {
"default": 0,
"enum": [
0,
1,
2
],
"type": "integer"
}
},
"size": {
"description": "Page size",
"example": 10,
"in": "query",
"name": "size",
"required": false,
"schema": {
"default": 10,
"maximum": 100,
"type": "integer"
}
},
"type": {
"description": "Set this parameter to filter the type of number, such as mobile or landline",
"example": "mobile-lvn",
"in": "query",
"name": "type",
"required": false,
"schema": {
"enum": [
"landline",
"mobile-lvn",
"landline-toll-free"
],
"type": "string"
}
}
},
"schemas": {
"account-unauthorized": {
"properties": {
"error-code": {
"description": "The status code of the response. `200` indicates a successful request.",
"example": "401",
"type": "string"
},
"error-code-label": {
"description": "The status code description",
"example": "authentication failed",
"type": "string"
}
},
"type": "object",
"xml": {
"name": "inbound-numbers"
}
},
"available-numbers": {
"properties": {
"count": {
"description": "The total amount of numbers available in the pool.",
"example": 1234,
"type": "integer"
},
"numbers": {
"description": "A paginated array of available numbers and their details.",
"items": {
"$ref": "#/components/schemas/availablenumber"
},
"type": "array"
}
},
"type": "object",
"xml": {
"name": "inbound-numbers"
}
},
"availablenumber": {
"properties": {
"cost": {
"description": "The monthly rental cost for this number, in Euros",
"example": "1.25",
"type": "string"
},
"country": {
"$ref": "#/components/schemas/country"
},
"features": {
"description": "The capabilities of the number: `SMS` or `VOICE` or `SMS,VOICE` or `SMS,MMS` or `VOICE,MMS` or `SMS,MMS,VOICE`",
"example": [
"VOICE",
"SMS",
"MMS"
],
"items": {
"type": "string"
},
"type": "array"
},
"msisdn": {
"description": "An available inbound virtual number.",
"example": "447700900000",
"type": "string"
},
"type": {
"description": "The type of number: `landline`, `landline-toll-free` or `mobile-lvn`",
"example": "mobile-lvn",
"type": "string"
}
},
"type": "object"
},
"country": {
"description": "The two character country code in ISO 3166-1 alpha-2 format",
"example": "GB",
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"inbound-numbers": {
"properties": {
"count": {
"description": "The total amount of numbers owned by the account",
"example": 1,
"type": "integer"
},
"numbers": {
"description": "A paginated array of numbers and their details",
"items": {
"$ref": "#/components/schemas/ownednumber"
},
"type": "array"
}
},
"type": "object",
"xml": {
"name": "inbound-numbers"
}
},
"number-details": {
"properties": {
"country": {
"$ref": "#/components/schemas/country"
},
"msisdn": {
"description": "An available inbound virtual number.",
"example": "447700900000",
"type": "string"
},
"target_api_key": {
"description": "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.",
"example": "1a2345b7",
"type": "string"
}
},
"required": [
"country",
"msisdn"
],
"type": "object"
},
"number-details-update": {
"properties": {
"app_id": {
"description": "The Application that will handle inbound traffic to this number.",
"example": "aaaaaaaa-bbbb-cccc-dddd-0123456789abc",
"type": "string"
},
"country": {
"$ref": "#/components/schemas/country"
},
"messagesCallbackType": {
"deprecated": true,
"description": "<strong>DEPRECATED</strong> - We recommend that you use `app_id` instead.\n\nSpecifies the Messages webhook type (always `app`) associated with this\nnumber and must be used with the `messagesCallbackValue` parameter.\n",
"enum": [
"app"
],
"example": "app",
"type": "string"
},
"messagesCallbackValue": {
"deprecated": true,
"description": "<strong>DEPRECATED</strong> - We recommend that you use `app_id` instead.\n\nSpecifies the Application ID of your Messages application.\nIt must be used with the `messagesCallbackType` parameter.\n",
"example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"type": "string"
},
"moHttpUrl": {
"description": "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.",
"example": "https://example.com/webhooks/inbound-sms",
"type": "string"
},
"moSmppSysType": {
"description": "The associated system type for your SMPP client",
"example": "inbound",
"type": "string"
},
"msisdn": {
"description": "An available inbound virtual number.",
"example": "447700900000",
"type": "string"
},
"voiceCallbackType": {
"description": "Specify whether inbound voice calls on your number are forwarded\nto a SIP or a telephone number. This must be used with the\n`voiceCallbackValue` parameter. If set, `sip` or `tel` are\nprioritized over the Voice capability in your Application.\n\n*Note: The `app` value is deprecated and will be removed in future.*\n",
"enum": [
"sip",
"tel",
"app"
],
"example": "tel",
"type": "string"
},
"voiceCallbackValue": {
"description": "A SIP URI or telephone number. Must be used with the `voiceCallbackType` parameter.",
"example": "447700900000",
"type": "string"
},
"voiceStatusCallback": {
"description": "A webhook URI for Vonage to send a request to when a call ends",
"example": "https://example.com/webhooks/status",
"type": "string"
}
},
"required": [
"country",
"msisdn"
],
"type": "object"
},
"ownednumber": {
"properties": {
"country": {
"$ref": "#/components/schemas/country"
},
"features": {
"description": "The capabilities of the number: `SMS` or `VOICE` or `SMS,VOICE` or `SMS,MMS` or `VOICE,MMS` or `SMS,MMS,VOICE`",
"example": [
"VOICE",
"SMS",
"MMS"
],
"items": {
"type": "string"
},
"type": "array"
},
"messagesCallbackType": {
"description": "The messages webhook type: always `app`",
"example": "app",
"type": "string"
},
"messagesCallbackValue": {
"description": "An Application ID",
"example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"type": "string"
},
"moHttpUrl": {
"description": "The URL of the webhook endpoint that handles inbound messages",
"example": "https://example.com/webhooks/inbound-sms",
"format": "url",
"type": "string"
},
"msisdn": {
"description": "An available inbound virtual number.",
"example": "447700900000",
"type": "string"
},
"type": {
"description": "The type of number: `landline`, `landline-toll-free` or `mobile-lvn`",
"example": "mobile-lvn",
"type": "string"
},
"voiceCallbackType": {
"description": "The voice webhook type: `sip`, `tel`, or `app`",
"example": "app",
"type": "string"
},
"voiceCallbackValue": {
"description": "A SIP URI, telephone number or Application ID",
"example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"type": "string"
}
},
"type": "object"
},
"response": {
"properties": {
"error-code": {
"description": "The status code of the response. `200` indicates a successful request.",
"example": "200",
"type": "string"
},
"error-code-label": {
"description": "The status code description",
"example": "success",
"type": "string"
}
},
"type": "object",
"xml": {
"name": "response"
}
},
"response420": {
"properties": {
"error-code": {
"description": "The status code of the response. `200` indicates a successful request.",
"example": "420",
"type": "string"
},
"error-code-label": {
"description": "More detail about what happened. For example you may need to request the number via the dashboard, or you may already own this number.",
"example": "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.",
"type": "string"
}
},
"type": "object",
"xml": {
"name": "response"
}
},
"unauthorized": {
"properties": {
"error-code": {
"description": "The status code of the response. `200` indicates a successful request.",
"example": "401",
"type": "string"
},
"error-code-label": {
"description": "The status code description",
"example": "authentication failed",
"type": "string"
}
},
"type": "object",
"xml": {
"name": "response"
}
}
},
"securitySchemes": {
"apiKey": {
"description": "You can find your API key in the [developer dashboard](https://dashboard.nexmo.com)",
"in": "query",
"name": "api_key",
"type": "apiKey"
},
"apiSecret": {
"description": "You can find your API secret in the [developer dashboard](https://dashboard.nexmo.com)",
"in": "query",
"name": "api_secret",
"type": "apiKey"
}
}
}
}