Skip to content
Permalink
main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
 
 
Cannot retrieve contributors at this time
openapi: "3.0.2"
info:
title: "Account API"
version: "1.0.4"
description: >-
Enables users to manage their Vonage API Account by programmable means. More information is available here: <https://developer.nexmo.com/account/overview>.
contact:
name: Vonage.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 Vonage API 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
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorAuthenticationFailedAccountBalance"
application/xml:
schema:
$ref: "#/components/schemas/ErrorAuthenticationFailedAccountBalance"
/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:
$ref: "#/components/schemas/topupRequest"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/success"
application/xml:
schema:
$ref: "#/components/schemas/success"
"401":
description: Not Authorised
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/ErrorAuthenticationFailed"
- $ref: "#/components/schemas/ErrorAutoReloadNotEnabled"
application/xml:
schema:
oneOf:
- $ref: "#/components/schemas/ErrorAuthenticationFailed"
- $ref: "#/components/schemas/ErrorAutoReloadNotEnabled"
/account/settings:
servers:
- url: "https://rest.nexmo.com"
post:
operationId: changeAccountSettings
summary: Change Account Settings
description: >-
Update the default webhook URLs 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. Vonage 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:
$ref: "#/components/schemas/accountSettingsRequest"
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
/account/register-sender:
servers:
- url: "https://rest.nexmo.com"
post:
operationId: registerSender
summary: Register an email sender
description: >-
Register an email sender with an API Key for using email with Verify V2.
parameters:
- $ref: "#/components/parameters/api_key_for_auth"
- $ref: "#/components/parameters/api_secret_for_auth"
tags:
- Configuration
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/registerEmailRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
"$ref": "#/components/schemas/registerEmailResponse"
/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:
$ref: "#/components/schemas/createSecretRequest"
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 the Vonage 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 Vonage 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 Vonage 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 Vonage 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:
registerEmailResponse:
type: object
properties:
name:
type: string
description: An optional name to be attached to this binding
example: optionalName
application_ids:
type: array
items:
type: string
description: An array of ApplicationID strings attached to the value provided.
example: ['6ec9eb7de1d34e77ac2c0ad597c9554a', '5dba5838689f402dba0c77957e2181f3']
value:
type: string
description: Value given to the provider to attach to the Application IDs.
example: alice@company.com
provider:
type: string
format: enum
description: Enum identifer of provider type.
example: "email"
enum:
- email
success:
type: object
xml:
name: response
properties:
"error-code":
example: "200"
"error-code-label":
example: "success"
accountBalance:
type: object
xml:
name: accountBalance
properties:
value:
type: number
description: The balance of the account, in EUR
example: 10.28
autoReload:
type: boolean
enum: [true, false]
example: false
description: Whether the account has auto-reloading enabled
accountSettings:
type: object
xml:
name: account-settings
properties:
mo-callback-url:
type: string
format: url
description: The current or updated inbound message webhook URI
example: https://example.com/webhooks/inbound-sms
dr-callback-url:
type: string
format: url
description: The current or updated delivery receipt webhook 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
ErrorAuthenticationFailedAccountBalance:
description: Authentication Failed
type: object
xml:
name: accountBalance
properties:
"error-code":
example: "401"
"error-code-label":
example: "authentication failed"
ErrorAuthenticationFailed:
description: Authentication Failed
type: object
xml:
name: response
properties:
"error-code":
example: "401"
"error-code-label":
example: "authentication failed"
ErrorAutoReloadNotEnabled:
description: Auto-Reload not enabled
type: object
xml:
name: response
properties:
"error-code":
example: "401"
"error-code-label":
example: "not auto-reload enabled"
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
registerEmailRequest:
type: object
required:
- provider
- value
properties:
provider:
description: >-
The delivery method by which the value would be assigned. Always `email`
type: string
format: enum
enum:
- email
example: email
value:
description: >-
The email adress to attach to the application(s)
type: string
format: email
example: bob@company.com
name:
description: >-
An optional name to be attached to this binding
type: string
example: my-email-link
application_ids:
description: >-
An optional array of additional ApplicationID's that the value is to be assigned to.
type: object
items:
type: string
example: ['6ec9eb7de1d34e77ac2c0ad597c9554a', '5dba5838689f402dba0c77957e2181f3']
accountSettingsRequest:
type: object
properties:
moCallBackUrl:
description: >-
The default webhook URL for inbound SMS. If an SMS is received at a Vonage number
that does not have its own inbound SMS webhook configured, Vonage makes a request
here.
Send an empty string to unset this value.
type: string
format: url
example: https://example.com/webhooks/inbound-sms
drCallBackUrl:
description: >-
The webhook URL that Vonage makes a request to when a delivery receipt is available
for an SMS sent by one of your Vonage numbers.
Send an empty string to unset this value.
type: string
format: url
example: https://example.com/webhooks/delivery-receipt
createSecretRequest:
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"
topupRequest:
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.
example: 8ef2447e69604f642ae59363aa5f781b
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/api-errors#unauthorized
title:
type: string
description: Description of the error
example: Unauthorized
detail:
type: string
description: More detail regarding this error, including the expected value
example: 'You did not provide correct credentials.'
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