{ "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: ", "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": "DEPRECATED - 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": "DEPRECATED - 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" } } } }