openapi-directory/api/nexmo.com/numbers.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

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