Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
2 contributors

Users who have contributed to this file

@marklewin @lornajane
418 lines (410 sloc) 13 KB
openapi: 3.0.0
info:
title: Numbers API
version: 1.0.8
description: >-
The Numbers API enables you to manage your existing numbers and buy new virtual numbers for
use with Nexmo's APIs. Further information is here: <https://developer.nexmo.com/numbers/overview>
contact:
name: Nexmo.com
email: devrel@nexmo.com
url: 'https://developer.nexmo.com'
x-twitter: Nexmo
termsOfService: 'https://www.nexmo.com/terms-of-use'
license:
name: The MIT License (MIT)
url: 'https://opensource.org/licenses/MIT'
x-logo:
url: 'https://twitter.com/Nexmo/profile_image?size=original'
x-apiClientRegistration: 'https://dashboard.nexmo.com/sign-up'
servers:
- url: 'https://rest.nexmo.com'
externalDocs:
description: Numbers product documentation on the Nexmo Developer Portal
url: 'https://developer.nexmo.com/numbers/overview'
security:
- apiKey: []
apiSecret: []
paths:
'/account/numbers':
get:
operationId: getOwnedNumbers
summary: List the numbers you own
description: Retrieve all the inbound numbers associated with your Nexmo account.
parameters:
- $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/pattern'
- $ref: '#/components/parameters/search_pattern'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/inbound-numbers'
text/xml:
schema:
$ref: '#/components/schemas/inbound-numbers'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error-code:
type: number
description: A code relating to this error
example: 401
error-code-label:
type: string
description: Words describing the error that occurred
example: authentication failed
'/number/search':
get:
operationId: getAvailableNumbers
summary: Search available numbers
description: Retrieve inbound numbers that are available for the specified country.
parameters:
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/type'
- $ref: '#/components/parameters/pattern'
- $ref: '#/components/parameters/search_pattern'
- name: features
required: false
in: query
description: >-
Available features are `SMS` and `VOICE`. To look for numbers that support both, use a
comma-separated value: `SMS,VOICE`.
schema:
type: string
enum:
- SMS
- VOICE
- 'SMS,VOICE'
example: SMS
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/index'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/available-numbers'
text/xml:
schema:
$ref: '#/components/schemas/available-numbers'
'401':
description: Unauthorized
'/number/buy':
post:
operationId: buyANumber
summary: Buy a number
description: Request to purchase a specific inbound number.
requestBody:
description: Number details
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/number-details'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/response'
text/xml:
schema:
$ref: '#/components/schemas/response'
'401':
description: Unauthorized
'/number/cancel':
post:
operationId: cancelANumber
summary: Cancel a number
description: Cancel your subscription for a specific inbound number.
requestBody:
description: Number details
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/number-details'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/response'
text/xml:
schema:
$ref: '#/components/schemas/response'
'401':
description: Unauthorized
'/number/update':
post:
operationId: updateANumber
summary: Update a number
description: Change the behaviour of a number that you own.
requestBody:
description: Number details
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/number-details-update'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/response'
text/xml:
schema:
$ref: '#/components/schemas/response'
'401':
description: Unauthorized
components:
securitySchemes:
apiKey:
type: apiKey
name: api_key
in: query
description: 'You can find your API key in the [developer dashboard](https://dashboard.nexmo.com)'
apiSecret:
type: apiKey
name: api_secret
in: query
description: 'You can find your API secret in the [developer dashboard](https://dashboard.nexmo.com)'
parameters:
index:
name: index
required: false
in: query
description: Page index
schema:
type: integer
default: 1
example: 1
size:
name: size
required: false
in: query
description: Page size
schema:
type: integer
maximum: 100
default: 10
example: 10
pattern:
name: pattern
required: false
in: query
description: The number pattern you want to search for. Use in conjunction with `search_pattern`.
schema:
type: string
example: '12345'
search_pattern:
name: search_pattern
required: false
in: query
description: |
The strategy you want to use for matching:
* `0` - Search for numbers that start with `pattern`
* `1` - Search for numbers that contain `pattern`
* `2` - Search for numbers that end with `pattern`
schema:
type: integer
default: 0
enum:
- 0
- 1
- 2
example: 1
country:
name: country
in: query
required: true
description: The two character country code in ISO 3166-1 alpha-2 format
schema:
type: string
example: GB
type:
name: type
in: query
required: false
description: Set this parameter to filter the type of number, such as mobile or landline
schema:
type: string
enum:
- landline
- mobile-lvn
- landline-toll-free
example: mobile-lvn
msisdn:
name: msisdn
required: true
in: query
description: The inbound number you want to cancel, in [E.164 international format](/concepts/guides/glossary#e-164-format)
schema:
type: string
example: '447700900000'
schemas:
number:
type: object
properties:
country:
type: string
example: GB
description: The two character country code in ISO 3166-1 alpha-2 format
msisdn:
type: string
example: '447700900000'
description: An available inbound virtual number.
moHttpUrl:
type: string
format: url
example: 'https://example.com/webhooks/inbound-sms'
description: >-
The URL of the webhook endpoint that handles inbound messages
type:
type: string
example: mobile-lvn
description: 'The type of number: `landline`, `landline-toll-free` or `mobile-lvn`'
features:
type: array
items:
type: string
example: [VOICE, SMS]
description: 'The capabilities of the number: `SMS` or `VOICE` or `SMS,VOICE`'
messagesCallbackType:
type: string
example: app
description: 'The messages webhook type: always `app`'
messagesCallbackValue:
type: string
example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
description: A Nexmo Application ID
voiceCallbackType:
type: string
example: app
description: 'The voice webhook type: `sip`, `tel`, or `app`'
voiceCallbackValue:
type: string
example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
description: A SIP URI, telephone number or Application ID
inbound-numbers:
type: object
properties:
count:
type: integer
description: The total amount of numbers owned by the account
example: 1
numbers:
type: array
description: A paginated array of numbers and their details
items:
$ref: '#/components/schemas/number'
available-numbers:
type: object
xml:
name: inbound-numbers
properties:
count:
type: integer
description: The total amount of numbers available in the pool.
example: 1234
numbers:
type: array
description: A paginated array of available numbers and their details.
items:
$ref: '#/components/schemas/number'
number-details:
type: object
properties:
country:
type: string
example: GB
description: The two character country code in ISO 3166-1 alpha-2 format
msisdn:
type: string
example: '447700900000'
description: An available inbound virtual number.
required:
- country
- msisdn
number-details-update:
type: object
properties:
country:
type: string
example: GB
description: The two character country code in ISO 3166-1 alpha-2 format
msisdn:
type: string
example: '447700900000'
description: An available inbound virtual number.
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. Nexmo 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.
type: string
example: 'https://example.com/webhooks/inbound-sms'
moSmppSysType:
description: The associated system type for your SMPP client
type: string
example: inbound
messagesCallbackType:
description: The SMS webhook type (always `app`). Must be used
with the `messagesCallbackValue` parameter.
type: string
enum:
- app
example: app
messagesCallbackValue:
description: >-
A Nexmo Application ID. Must be used
with the `messagesCallbackType` parameter.
type: string
example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
voiceCallbackType:
description: The voice webhook type. Must be used
with the `voiceCallbackValue` parameter.
type: string
enum:
- sip
- tel
- app
example: sip
voiceCallbackValue:
description: >-
A SIP URI, telephone number or Application ID. Must be used
with the `voiceCallbackType` parameter.
type: string
example: '447700900000'
voiceStatusCallback:
description: A webhook URI for Nexmo to send a request to when a call ends
type: string
example: 'https://example.com/webhooks/status'
required:
- country
- msisdn
response:
type: object
properties:
error-code:
type: integer
example: 200
description: The status code of the response. `200` indicates a successful request.
error-code-label:
type: string
example: success
description: The status code description
You can’t perform that action at this time.