Enables users to manage their Vonage API Account by programmable means. More information is available here: https://developer.nexmo.com/account/overview.
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.
Manage the settings on your account
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.
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.
Retrieve the current balance of your Vonage API account
GET
https://rest.nexmo.com/account/get-balance
Host
https://rest.nexmo.com
GET
/account/get-balance
Your Vonage API key. You can find this in the dashboard
Your Vonage API secret. You can find this in the dashboard
The balance of the account, in EUR
Whether the account has auto-reloading enabled
One of:true
or false
The balance of the account, in EUR
Whether the account has auto-reloading enabled
One of:true
or false
{
"value": 10.28,
"autoReload": false
}
<?xml version="1.0" encoding="UTF-8"?>
<accountBalance>
<value>10.28</value>
<autoReload>false</autoReload>
</accountBalance>
{
"error-code": "401",
"error-code-label": "authentication failed"
}
<?xml version="1.0" encoding="UTF-8"?>
<accountBalance>
<error-code>401</error-code>
<error-code-label>authentication failed</error-code-label>
</accountBalance>
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.
POST
https://rest.nexmo.com/account/top-up
Host
https://rest.nexmo.com
POST
/account/top-up
Your Vonage API key. You can find this in the dashboard
Your Vonage API secret. You can find this in the dashboard
The transaction reference of the transaction when balance was added and auto-reload was enabled on your account.
POST /account/top-up HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 36
trx=8ef2447e69604f642ae59363aa5f781b
{
"error-code": "200",
"error-code-label": "success"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error-code>200</error-code>
<error-code-label>success</error-code-label>
</response>
{
"error-code": "401",
"error-code-label": "authentication failed"
}
{
"error-code": "401",
"error-code-label": "not auto-reload enabled"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error-code>401</error-code>
<error-code-label>authentication failed</error-code-label>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error-code>401</error-code>
<error-code-label>not auto-reload enabled</error-code-label>
</response>
Manage the settings on your account
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.
POST
https://rest.nexmo.com/account/settings
Host
https://rest.nexmo.com
POST
/account/settings
Your Vonage API key. You can find this in the dashboard
Your Vonage API secret. You can find this in the dashboard
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.
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.
The current or updated inbound message webhook URI
The current or updated delivery receipt webhook URI
The maximum number of outbound messages per second.
The maximum number of inbound messages per second.
The maximum number of API calls per second.
The current or updated inbound message webhook URI
The current or updated delivery receipt webhook URI
The maximum number of outbound messages per second.
The maximum number of inbound messages per second.
The maximum number of API calls per second.
POST /account/settings HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 134
moCallBackUrl=https%3A%2F%2Fexample.com%2Fwebhooks%2Finbound-sms&drCallBackUrl=https%3A%2F%2Fexample.com%2Fwebhooks%2Fdelivery-receipt
{
"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
}
<?xml version="1.0" encoding="UTF-8"?>
<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>
This endpoint does not support application/json
This endpoint does not support application/xml
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.
GET
https://api.nexmo.com/accounts/:api_key/secrets
Host
https://api.nexmo.com
GET
/accounts/:api_key/secrets
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The API key to manage secrets for
The single secrets
key returns an array of API secrets
Array of API secrets
Secret ID
Creation date/time for this secret
This endpoint does not support application/xml
{
"_links": {
"self": {
"href": "abc123"
}
},
"_embedded": {
"secrets": [
{
"_links": {
"self": {
"href": "abc123"
}
},
"id": "ad6dc56f-07b5-46e1-a527-85530e625800",
"created_at": "2017-03-02T16:34:49Z"
}
]
}
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/",
"title": "Unauthorized",
"detail": "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\"",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/api-errors#invalid-api-key",
"title": "Invalid API Key",
"detail": "API key 'abc123' not found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
POST
https://api.nexmo.com/accounts/:api_key/secrets
Host
https://api.nexmo.com
POST
/accounts/:api_key/secrets
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The API key to manage secrets for
The new secret must follow these rules:
Secret ID
Creation date/time for this secret
This endpoint does not support application/xml
{
"secret": "example-4PI-secret"
}
{
"_links": {
"self": {
"href": "abc123"
}
},
"id": "ad6dc56f-07b5-46e1-a527-85530e625800",
"created_at": "2017-03-02T16:34:49Z"
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/api-errors/account/secret-management#validation",
"title": "Bad Request",
"detail": "The request failed due to secret validation errors",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
"invalid_parameters": [
{
"name": "secret",
"reason": "Does not meet complexity requirements"
}
]
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/",
"title": "Unauthorized",
"detail": "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\"",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/api-errors#invalid-api-key",
"title": "Invalid API Key",
"detail": "API key 'abc123' not found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
GET
https://api.nexmo.com/accounts/:api_key/secrets/:secret_id
Host
https://api.nexmo.com
GET
/accounts/:api_key/secrets/:secret_id
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The API key to manage secrets for
ID of the API Secret
Secret ID
Creation date/time for this secret
This endpoint does not support application/xml
{
"_links": {
"self": {
"href": "abc123"
}
},
"id": "ad6dc56f-07b5-46e1-a527-85530e625800",
"created_at": "2017-03-02T16:34:49Z"
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/",
"title": "Unauthorized",
"detail": "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\"",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/api-errors#invalid-api-key",
"title": "Invalid API Key",
"detail": "API key 'abc123' not found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
"type": "https://developer.nexmo.com/api-errors#invalid-id",
"title": "Invalid ID",
"detail": "ID '07239aeb-d756-4c32-a1de-cf64f8b21827' could not be found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
DELETE
https://api.nexmo.com/accounts/:api_key/secrets/:secret_id
Host
https://api.nexmo.com
DELETE
/accounts/:api_key/secrets/:secret_id
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The API key to manage secrets for
ID of the API Secret
Revoked secret response (without body content)
{
"type": "https://developer.nexmo.com/",
"title": "Unauthorized",
"detail": "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\"",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/api-errors/account/secret-management#delete-last-secret",
"title": "Secret Deletion Forbidden",
"detail": "Can not delete the last secret. The account must always have at least 1 secret active at any time",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
{
"type": "https://developer.nexmo.com/api-errors#invalid-api-key",
"title": "Invalid API Key",
"detail": "API key 'abc123' not found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
"type": "https://developer.nexmo.com/api-errors#invalid-id",
"title": "Invalid ID",
"detail": "ID '07239aeb-d756-4c32-a1de-cf64f8b21827' could not be found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
This endpoint does not support application/xml
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 | Details |
---|---|
validation | The provided payload is invalid |
delete-last-secret | You can not delete your only API secret |