Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
618 lines (597 sloc) 22.4 KB
openapi: "3.0.2"
info:
title: "Nexmo Account API"
version: "1.0.0"
description : >-
Enables users to manage their Nexmo Account by programmable means. More information is available here: <https://developer.nexmo.com/account/overview>.
contact:
name: Nexmo.com
url: "https://developer.nexmo.com"
servers:
- url: "https://api.nexmo.com"
paths:
/account/get-balance:
servers:
- url: "https://rest.nexmo.com"
get:
operationId: getAccountBalance
summary: Get Account Balance
description: Retrieve the current balance of your Nexmo account
parameters:
- $ref: '#/components/parameters/api_key_for_auth'
- $ref: '#/components/parameters/api_secret_for_auth'
tags:
- Balance
responses:
'200':
description: The current balance of your account
content:
application/json:
schema:
$ref: '#/components/schemas/accountBalance'
example: {"value":10.17127500,"autoReload":false}
application/xml:
schema:
$ref: '#/components/schemas/accountBalance'
example: >-
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<accountBalance>
<value>10.17127500</value>
<autoReload>false</autoReload>
</accountBalance>
'401':
description: Not Authorised. You must supply your `api_key` and `api_secret` as query parameters to this request
/account/top-up:
servers:
- url: "https://rest.nexmo.com"
post:
operationId: topUpAccountBalance
summary: Top Up Account Balance
description: >-
You can top up your account using this API when you have enabled auto-reload in the
dashboard. The amount added by the top-up operation will be the same amount as was
added in the payment when auto-reload was enabled.
Your account balance is checked every 5-10 minutes and if it falls below the threshold
and auto-reload is enabled, then it will be topped up automatically. Use this endpoint
if you need to top up at times when your credit may be exhausted more quickly than the
auto-reload may occur.
externalDocs:
url: "https://help.nexmo.com/hc/en-us/articles/205603248-How-do-I-set-up-automatic-payments-using-PayPal-or-credit-card-"
description: Read more about automatic payments on the Knowledgebase
parameters:
- $ref: '#/components/parameters/api_key_for_auth'
- $ref: '#/components/parameters/api_secret_for_auth'
tags:
- Balance
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- trx
properties:
trx:
type: string
description: The transaction reference of the transaction when balance was added and auto-reload was enabled on your account.
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
response:
type: string
example: "success"
application/xml:
schema:
type: object
properties:
response:
type: string
example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?><response>success</response>
'401':
description: Not Authorised. You must supply your `api_key` and `api_secret` as query parameters to this request
/account/settings:
servers:
- url: "https://rest.nexmo.com"
post:
operationId: changeAccountSettings
summary: Change Account Settings
description: >-
Update the default callback URLs (where the webhooks are sent to) associated with your account:
* Callback URL for incoming SMS messages
* Callback URL for delivery receipts
Note that the URLs you provide must be valid and active. Nexmo will check that they
return a 200 OK response before the setting is saved.
parameters:
- $ref: '#/components/parameters/api_key_for_auth'
- $ref: '#/components/parameters/api_secret_for_auth'
tags:
- Configuration
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
moCallBackUrl:
description: >-
The URL where Nexmo will send a webhook when an SMS is received
to a Nexmo number that does not have SMS handling configured.
Send an empty string to unset this value.
type: string
format: url
example: https://example.com/webhooks/inbound-sms
drCallBackUrl:
description: >-
The URL where Nexmo will send a webhook when an delivery
receipt is received without a specific callback URL configured.
Send an empty string to unset this value.
type: string
format: url
example: https://example.com/webhooks/delivery-receipt
responses:
'200':
description: OK. Settings were updated if supplied, the details of the current settings are included in the response.
content:
application/json:
schema:
$ref: '#/components/schemas/accountSettings'
example: >-
{
"mo-callback-url": "https:\/\/example.com\/webhooks\/inbound-sms",
"dr-callback-url": "https:\/\/example.com\/webhooks\/delivery-receipt",
"max-outbound-request": 30,
"max-inbound-request": 30,
"max-calls-per-second": 30
}
application/xml:
schema:
$ref: '#/components/schemas/accountSettings'
example: >-
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<account-settings>
<mo-callback-url>https://example.com/webhooks/inbound-sms</mo-callback-url>
<dr-callback-url>https://example.com/webhooks/delivery-receipt</dr-callback-url>
<max-outbound-request>30</max-outbound-request>
<max-inbound-request>30</max-inbound-request>
<max-calls-per-second>30</max-calls-per-second>
</account-settings>
'401':
description: Not Authorised. You must supply your `api_key` and `api_secret` as query parameters to this request
/accounts/{api_key}/secrets:
get:
summary: Retrieve API Secrets
operationId: retrieveAPISecrets
tags:
- Secret Management
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/APIKey'
responses:
'200':
description: The list of your current API secrets
content:
application/json:
schema:
properties:
_links:
$ref: '#/components/schemas/secretMgmtLinks'
_embedded:
type: object
description: The single `secrets` key returns an array of API secrets
properties:
secrets:
type: array
description: Array of API secrets
items:
$ref: '#/components/schemas/secretInfo'
example: >-
{
"_links": {
"self": {
"href": "/accounts/abcd1234/secrets"
}
},
"_embedded": {
"secrets": [
{
"_links": {
"self": {
"href": "/accounts/abcd1234/secrets/01234567-aaaa-bbbb-cccc-defdefdefdef"
}
},
"id": "01234567-aaaa-bbbb-cccc-defdefdefdef",
"created_at": "2018-12-03T10:07:23Z"
}
]
}
}
'401':
$ref: '#/components/responses/BadCredentialsError'
'404':
description: "Item not found"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorAPIKeyNotFound'
post:
summary: Create API Secret
operationId: createAPISecret
tags:
- Secret Management
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/APIKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- secret
properties:
secret:
description: |
The new secret must follow these rules:
* minimum 8 characters
* maximum 25 characters
* minimum 1 lower case character
* minimum 1 upper case character
* minimum 1 digit
type: string
example: 'example-4PI-secret'
responses:
'201':
description: Secret created
content:
application/json:
schema:
$ref: '#/components/schemas/secretInfo'
example: >-
{
"_links": {
"self": {
"href": "/accounts/abcd1234/secrets/01234567-aaaa-bbbb-cccc-defdefdefdef"
}
},
"id": "01234567-aaaa-bbbb-cccc-defdefdefdef",
"created_at": "2018-12-03T10:07:23Z"
}
'400':
description: Bad request. This usually indicates valid data but can also occur when a user has exceeded the allowed number of secrets on their account.
content:
application/json:
schema:
properties:
type:
type: string
description: URL for further information
example: https://developer.nexmo.com/api-errors/account/secret-management#validation
title:
type: string
description: Description of the error
example: Bad Request
detail:
type: string
description: More detail regarding this error, including the API key supplied
example: The request failed due to secret validation errors
instance:
type: string
description: Internal Trace ID
example: bf0ca0bf927b3b52e3cb03217e1a1ddf
invalid_parameters:
type: array
description: Array of the parameters that are considered invalid, and explanations of why
items:
type: object
properties:
name:
type: string
description: Field name
example: secret
reason:
type: string
description: Explanation of why parameter is considered invalid
example: Does not meet complexity requirements
'401':
$ref: '#/components/responses/BadCredentialsError'
'404':
description: "Item not found"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorAPIKeyNotFound'
/accounts/{api_key}/secrets/{secret_id}:
get:
summary: Retrieve one API Secret
operationId: retrieveAPISecret
tags:
- Secret Management
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/APIKey'
- $ref: '#/components/parameters/secretId'
responses:
'200':
description: API secret response
content:
application/json:
schema:
$ref: '#/components/schemas/secretInfo'
example: >-
{
"_links": {
"self": {
"href": "/accounts/abcd1234/secrets/01234567-aaaa-bbbb-cccc-defdefdefdef"
}
},
"id": "01234567-aaaa-bbbb-cccc-defdefdefdef",
"created_at": "2018-12-03T10:07:23Z"
}
'401':
$ref: '#/components/responses/BadCredentialsError'
'404':
description: "Item not found"
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorAPIKeyNotFound'
- $ref: '#/components/schemas/ErrorSecretIDNotFound'
delete:
summary: Revoke an API Secret
operationId: revokeAPISecret
tags:
- Secret Management
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/APIKey'
- $ref: '#/components/parameters/secretId'
responses:
'204':
description: Revoked secret response (without body content)
'401':
$ref: '#/components/responses/BadCredentialsError'
'403':
description: Operation forbidden by permissions or because this is the only API secret and you are required to have at least one.
content:
application/json:
schema:
properties:
type:
type: string
description: URL for further information
example: https://developer.nexmo.com/api-errors/account/secret-management#delete-last-secret
title:
type: string
description: Description of the error
example: Secret Deletion Forbidden
detail:
type: string
description: More detail regarding this error
example: Can not delete the last secret. The account must always have at least 1 secret active at any time
instance:
type: string
description: Internal Trace ID
example: bf0ca0bf927b3b52e3cb03217e1a1ddf
'404':
description: "Item not found"
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorAPIKeyNotFound'
- $ref: '#/components/schemas/ErrorSecretIDNotFound'
tags:
- name: Balance
description: This section shows how you can query the current balance of your account, and if you have auto-reload enabled how to trigger a top-up to your account without waiting for the next balance check.
- name: Configuration
description: Manage the settings on your account
- name: Secret Management
description: >-
Many of Nexmo's APIs are accessed using an API key and secret. It is recommended that you change or "rotate" your secrets from time to time for security purposes. This section provides the API interface for achieving this.
Note: to work on secrets for your secondary accounts, you may authenticate with your primary credentials and supply the secondary API keys as URL parameters to these API endpoints.
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Provide an `Authorization` header, with a value of "Basic" followed by the result of base64-encoding your Nexmo API key and secret separated by a colon. You can find your API key and secret on the [dashboard](https://dashboard.nexmo.com) and more information is available [on the developer portal](https://developer.nexmo.com/concepts/guides/authentication#header-based-api-key-and-secret-authentication).
If your API key were aaa012 and your API secret were abc123456789 then your HTTP header would be: `Authorization: Basic YWFhMDEyOmFiYzEyMzQ1Njc4OQ==`
parameters:
api_key_for_auth:
name: api_key
description: Your Nexmo API key. You can find this in the [dashboard](https://dashboard.nexmo.com)
in: query
required: true
schema:
type: string
example: abcd1234
api_secret_for_auth:
name: api_secret
description: Your Nexmo API secret. You can find this in the [dashboard](https://dashboard.nexmo.com)
in: query
required: true
schema:
type: string
example: ABCDEFGH01234abc
APIKey:
name: api_key
in: path
description: The API key to manage secrets for
example: abcd1234
required: true
schema:
type: string
secretId:
name: secret_id
in: path
description: ID of the API Secret
example: 01234567-aaaa-bbbb-cccc-defdefdefdef
required: true
schema:
type: string
schemas:
accountBalance:
type: object
xml:
name: accountBalance
properties:
value:
type: number
description: The balance of the account, in EUR
autoReload:
type: boolean
enum: [true, false]
description: Whether the account has auto-reloading enabled
accountSettings:
type: object
properties:
mo-callback-url:
type: string
format: url
description: The current or updated inbound message URI
example: https://example.com/webhooks/inbound-sms
dr-callback-url:
type: string
format: url
description: The current or updated delivery receipt URI
example: https://example.com/webhooks/delivery-receipt
max-outbound-request:
type: integer
description: The maximum number of outbound messages per second.
example: 30
max-inbound-request:
type: integer
description: The maximum number of inbound messages per second.
example: 30
max-calls-per-second:
type: integer
description: The maximum number of API calls per second.
example: 30
secretInfo:
type: object
properties:
_links:
$ref: '#/components/schemas/secretMgmtLinks'
id:
type: string
description: Secret ID
example: ad6dc56f-07b5-46e1-a527-85530e625800
created_at:
type: string
description: Creation date/time for this secret
example: '2017-03-02T16:34:49Z'
secretMgmtLinks:
type: object
description: Links related to this resource
properties:
self:
type: object
description: This resource
properties:
href:
type: string
description: The URI for this resource
ErrorAPIKeyNotFound:
description: This API key was not recognised
type: object
required:
- type
- title
- detail
- instance
properties:
type:
type: string
description: URL for further information
# example: https://developer.nexmo.com/api-errors#invalid-id
example: https://developer.nexmo.com/api-errors#invalid-api-key
title:
type: string
description: Description of the error
example: Invalid API Key
detail:
type: string
description: More detail regarding this error, including the API key supplied
example: API key 'abc123' not found
instance:
type: string
description: Internal Trace ID
example: bf0ca0bf927b3b52e3cb03217e1a1ddf
ErrorSecretIDNotFound:
description: This secret ID was not recognised
type: object
required:
- type
- title
- detail
- instance
properties:
type:
type: string
description: URL for further information
example: https://developer.nexmo.com/api-errors#invalid-id
title:
type: string
description: Description of the error
example: Invalid ID
detail:
type: string
description: More detail regarding this error, including the secret ID supplied
example: ID '07239aeb-d756-4c32-a1de-cf64f8b21827' could not be found
instance:
type: string
description: Internal Trace ID
example: bf0ca0bf927b3b52e3cb03217e1a1ddf
responses:
BadCredentialsError:
description: Credentials are missing or invalid
content:
application/json:
schema:
properties:
type:
type: string
description: URL for further information
example: https://developer.nexmo.com/
title:
type: string
description: Description of the error
example: Unauthorized
detail:
type: string
description: More detail regarding this error, including the expected value
example: "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\""
instance:
type: string
description: Internal Trace ID
example: bf0ca0bf927b3b52e3cb03217e1a1ddf
x-errors:
validation:
description: The provided payload is invalid
resolution: |
Modify your request to provide a valid payload.
* Minimum 8 characters
* Maximum 25 characters
* Minimum 1 lower case character
* Minimum 1 upper case character
* Minimum 1 digit
link:
text: View API reference
url: /api/account/api-secret-management#createSecret
delete-last-secret:
description: You can not delete your only API secret
resolution: Add another API secret before deleting this one
You can’t perform that action at this time.