Enables users to manage their Nexmo 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.
Retrieve the current balance of your Nexmo account
GET
https://rest.nexmo.com/account/get-balance
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
Your Nexmo API key. You can find this in the dashboard |
abcd1234
|
None |
api_secret Required | string |
Your Nexmo API secret. You can find this in the dashboard |
ABCDEFGH01234abc
|
None |
View response field descriptions
Field | Description |
---|---|
value
number |
The balance of the account, in EUR |
autoReload
boolean |
Whether the account has auto-reloading enabled One of:true or false
|
Field | Description |
---|---|
value
number |
The balance of the account, in EUR |
autoReload
boolean |
Whether the account has auto-reloading enabled One of:true or false
|
{
"value": 1,
"autoReload": false
}
<?xml version="1.0" encoding="UTF-8"?>
<accountBalance>
<value>1.0</value>
<autoReload>false</autoReload>
</accountBalance>
Not Authorised. You must supply your `api_key` and `api_secret` as query parameters to this request
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
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
Your Nexmo API key. You can find this in the dashboard |
abcd1234
|
None |
api_secret Required | string |
Your Nexmo API secret. You can find this in the dashboard |
ABCDEFGH01234abc
|
None |
Key | Description | Example | Default |
---|---|---|---|
trx Required | string |
The transaction reference of the transaction when balance was added and auto-reload was enabled on your account. |
None | None |
View response field descriptions
Field | Description |
---|---|
response
string |
Field | Description |
---|---|
response
string |
{
"response": "abc123"
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<response>abc123</response>
</hash>
Not Authorised. You must supply your `api_key` and `api_secret` as query parameters to this request
Manage the settings on your account
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.
POST
https://rest.nexmo.com/account/settings
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
Your Nexmo API key. You can find this in the dashboard |
abcd1234
|
None |
api_secret Required | string |
Your Nexmo API secret. You can find this in the dashboard |
ABCDEFGH01234abc
|
None |
Key | Description | Example | Default |
---|---|---|---|
moCallBackUrl string | (url) |
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. |
https://example.com/webhooks/inbound-sms
|
None |
drCallBackUrl string | (url) |
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. |
https://example.com/webhooks/delivery-receipt
|
None |
View response field descriptions
Field | Description |
---|---|
mo-callback-url
string |
The current or updated inbound message URI |
dr-callback-url
string |
The current or updated delivery receipt URI |
max-outbound-request
integer |
The maximum number of outbound messages per second. |
max-inbound-request
integer |
The maximum number of inbound messages per second. |
max-calls-per-second
integer |
The maximum number of API calls per second. |
Field | Description |
---|---|
mo-callback-url
string |
The current or updated inbound message URI |
dr-callback-url
string |
The current or updated delivery receipt URI |
max-outbound-request
integer |
The maximum number of outbound messages per second. |
max-inbound-request
integer |
The maximum number of inbound messages per second. |
max-calls-per-second
integer |
The maximum number of API calls per second. |
{
"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"?>
<hash>
<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>
</hash>
Not Authorised. You must supply your `api_key` and `api_secret` as query parameters to this request
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.
GET
https://api.nexmo.com/accounts/:api_key/secrets
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
The API key to manage secrets for |
abcd1234
|
None |
View response field descriptions
Field | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
_embedded
object |
The single |
||||||||||||
|
{
"_links": {
"self": {
"href": "abc123"
}
},
"_embedded": {
"secrets": [
{
"_links": {
"self": {
"href": "abc123"
}
},
"id": "ad6dc56f-07b5-46e1-a527-85530e625800",
"created_at": "2017-03-02T16:34:49Z"
}
]
}
}
{
"type": "https://developer.nexmo.com/",
"title": "Unauthorized",
"detail": "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\"",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
"type": "https://developer.nexmo.com/api-errors#invalid-api-key",
"title": "Invalid API Key",
"detail": "API key 'abc123' not found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
POST
https://api.nexmo.com/accounts/:api_key/secrets
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
The API key to manage secrets for |
abcd1234
|
None |
Key | Description | Example | Default |
---|---|---|---|
secret Required | string |
The new secret must follow these rules:
|
example-4PI-secret
|
None |
View response field descriptions
Field | Description |
---|---|
id
string |
Secret ID |
created_at
string |
Creation date/time for this secret |
{
"_links": {
"self": {
"href": "abc123"
}
},
"id": "ad6dc56f-07b5-46e1-a527-85530e625800",
"created_at": "2017-03-02T16:34:49Z"
}
{
"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"
}
]
}
{
"type": "https://developer.nexmo.com/",
"title": "Unauthorized",
"detail": "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\"",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
"type": "https://developer.nexmo.com/api-errors#invalid-api-key",
"title": "Invalid API Key",
"detail": "API key 'abc123' not found",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
GET
https://api.nexmo.com/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 |
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
The API key to manage secrets for |
abcd1234
|
None |
secret_id Required | string |
ID of the API Secret |
01234567-aaaa-bbbb-cccc-defdefdefdef
|
None |
View response field descriptions
Field | Description |
---|---|
id
string |
Secret ID |
created_at
string |
Creation date/time for this secret |
{
"_links": {
"self": {
"href": "abc123"
}
},
"id": "ad6dc56f-07b5-46e1-a527-85530e625800",
"created_at": "2017-03-02T16:34:49Z"
}
{
"type": "https://developer.nexmo.com/",
"title": "Unauthorized",
"detail": "Invalid credentials format. Expected: \"Authorization: (Base64(UTF-8(apiKey:secret)))\"",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
"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"
}
DELETE
https://api.nexmo.com/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 |
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
The API key to manage secrets for |
abcd1234
|
None |
secret_id Required | string |
ID of the API Secret |
01234567-aaaa-bbbb-cccc-defdefdefdef
|
None |
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"
}
{
"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"
}
{
"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"
}