Account API

Enables users to manage their Vonage API Account by programmable means. More information is available here: https://developer.nexmo.com/en/account/overview.

Download OpenAPI Specification

Balance

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.

Available Operations

Get Account Balance

Retrieve the current balance of your Vonage API account

gethttps://rest.nexmo.com/account/get-balance

Query Parameters

api_key

string

exampleabcd1234

Your Vonage API key. You can find this in the dashboard

api_secret

string

exampleABCDEFGH01234abc

Your Vonage API secret. You can find this in the dashboard

Responses
Content Type
application/json

The current balance of your account

value

number

example10.28

The balance of the account, in EUR

autoReload

boolean

Whether the account has auto-reloading enabled

Must be one of:truefalse

Example Response

{
   "value": 10.28,
   "autoReload": false
}

Top Up Account Balance

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.

posthttps://rest.nexmo.com/account/top-up

Query Parameters

api_key

string

exampleabcd1234

Your Vonage API key. You can find this in the dashboard

api_secret

string

exampleABCDEFGH01234abc

Your Vonage API secret. You can find this in the dashboard

Request Body
Content Type
application/x-www-form-urlencoded

trx

string

Required

example8ef2447e69604f642ae59363aa5f781b

The transaction reference of the transaction when balance was added and auto-reload was enabled on your account.

Example Request

POST /account/top-up HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 36

trx=8ef2447e69604f642ae59363aa5f781b

POST /account/top-up HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 36

trx=8ef2447e69604f642ae59363aa5f781b

Responses
Content Type
application/json

Success

error-code

example200

error-code-label

examplesuccess

Example Response

{
   "error-code": "200",
   "error-code-label": "success"
}

Configuration

Manage the settings on your account

Available Operations

Change Account Settings

Change Account Settings

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.

posthttps://rest.nexmo.com/account/settings

Query Parameters

api_key

string

exampleabcd1234

Your Vonage API key. You can find this in the dashboard

api_secret

string

exampleABCDEFGH01234abc

Your Vonage API secret. You can find this in the dashboard

Request Body
Content Type
application/x-www-form-urlencoded

moCallBackUrl

string(url)

examplehttps://example.com/webhooks/inbound-sms

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.

drCallBackUrl

string(url)

examplehttps://example.com/webhooks/delivery-receipt

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.

Example Request

POST /account/settings HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 114

moCallBackUrl=https://example.com/webhooks/inbound-sms&drCallBackUrl=https://example.com/webhooks/delivery-receipt

POST /account/settings HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 114

moCallBackUrl=https://example.com/webhooks/inbound-sms&drCallBackUrl=https://example.com/webhooks/delivery-receipt

Responses
Content Type
application/json

OK. Settings were updated if supplied, the details of the current settings are included in the response.

mo-callback-url

string(url)

examplehttps://example.com/webhooks/inbound-sms

The current or updated inbound message webhook URI

dr-callback-url

string(url)

examplehttps://example.com/webhooks/delivery-receipt

The current or updated delivery receipt webhook URI

max-outbound-request

integer

example30

The maximum number of outbound messages per second.

max-inbound-request

integer

example30

The maximum number of inbound messages per second.

max-calls-per-second

integer

example30

The maximum number of API calls per second.

Example Response

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

Secret Management

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.

Available Operations

Retrieve API Secrets

gethttps://api.nexmo.com/accounts/:api_key/secrets

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`
	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](${CUSTOMER_DASHBOARD_URL}) 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==`

Path Parameters

api_key

string

Required

The API key to manage secrets for

Responses
Content Type
application/json

The list of your current API secrets

_links

object

Links related to this resource

self

object

This resource

href

string

The URI for this resource

_embedded

object

The single secrets key returns an array of API secrets

secrets

array

Array of API secrets

_links

object

Links related to this resource

self

object

This resource

href

string

The URI for this resource

string

examplead6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at

string

example2017-03-02T16:34:49Z

Creation date/time for this secret

Example Response

{
   "_links": {
      "self": {
         "href": "string"
      }
   },
   "_embedded": {
      "secrets": [
         {
            "_links": {
               "self": {
                  "href": "string"
               }
            },
            "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
            "created_at": "2017-03-02T16:34:49Z"
         }
      ]
   }
}

Create API Secret

posthttps://api.nexmo.com/accounts/:api_key/secrets

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`
	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](${CUSTOMER_DASHBOARD_URL}) 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==`

Path Parameters

api_key

string

Required

The API key to manage secrets for

Request Body
Content Type
application/json

secret

string

Required

exampleexample-4PI-secret

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

Example Request

{
   "secret": "example-4PI-secret"
}

{
   "secret": "example-4PI-secret"
}

Responses
Content Type
application/json

Secret created

_links

object

Links related to this resource

self

object

This resource

href

string

The URI for this resource

string

examplead6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at

string

example2017-03-02T16:34:49Z

Creation date/time for this secret

Example Response

{
   "_links": {
      "self": {
         "href": "string"
      }
   },
   "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
   "created_at": "2017-03-02T16:34:49Z"
}

Retrieve one API Secret

gethttps://api.nexmo.com/accounts/:api_key/secrets/:secret_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`
	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](${CUSTOMER_DASHBOARD_URL}) 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==`

Path Parameters

api_key

string

Required

The API key to manage secrets for

secret_id

string

Required

ID of the API Secret

Responses
Content Type
application/json

API secret response

_links

object

Links related to this resource

self

object

This resource

href

string

The URI for this resource

string

examplead6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at

string

example2017-03-02T16:34:49Z

Creation date/time for this secret

Example Response

{
   "_links": {
      "self": {
         "href": "string"
      }
   },
   "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
   "created_at": "2017-03-02T16:34:49Z"
}

Revoke an API Secret

deletehttps://api.nexmo.com/accounts/:api_key/secrets/:secret_id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`
	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](${CUSTOMER_DASHBOARD_URL}) 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==`

Path Parameters

api_key

string

Required

The API key to manage secrets for

secret_id

string

Required

ID of the API Secret

Responses

Revoked secret response (without body content)

Errors

The following is a non-exhaustive list of error codes that may occur while using this API.

These codes are in addition to any of our generic error codes.

Code	Information
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
delete-last-secret	Description You can not delete your only API secret Resolution Add another API secret before deleting this one

Code

Information

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

delete-last-secret

Description

You can not delete your only API secret

Resolution

Add another API secret before deleting this one

Account API

Balance

Available Operations

Get Account Balance

Query Parameters

Responses Content Typeapplication/json

Example Response

Top Up Account Balance

Query Parameters

Request Body Content Typeapplication/x-www-form-urlencoded

Example Request

Responses Content Typeapplication/json

Example Response

Configuration

Available Operations

Change Account Settings

Query Parameters

Request Body Content Typeapplication/x-www-form-urlencoded

Example Request

Responses Content Typeapplication/json

Example Response

Secret Management

Available Operations

Retrieve API Secrets

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Create API Secret

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve one API Secret

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Revoke an API Secret

Authentication

Path Parameters

Responses

Errors

Responses
Content Type
application/json

Request Body
Content Type
application/x-www-form-urlencoded

Responses
Content Type
application/json

Request Body
Content Type
application/x-www-form-urlencoded

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json