Nexmo Account API

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

Download OpenAPI 3 Definition

Improve this 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.

Get Account Balance

Retrieve the current balance of your Nexmo account

GET


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

Query Parameter

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

Response Fields

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

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.

POST


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

Query Parameter

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

Request body application/x-www-form-urlencoded

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

Response Fields

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

Configuration

Manage the settings on your account

Change Account Settings

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

Query Parameter

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

Request body application/x-www-form-urlencoded

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

Response Fields

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

Secret Management

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.

Retrieve API Secrets

GET


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

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Path Parameters

Key	Description	Example	Default
api_key Required \| string	The API key to manage secrets for	`abcd1234`	None

View response field descriptions

Response Fields

Field Description

_embedded
object

The single secrets key returns an array of API secrets

Field

Description

secrets
array of objects

Array of API secrets

Field	Description
id string	Secret ID
created_at string	Creation date/time for this secret

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

Create API Secret

POST


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

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Path Parameters

Key	Description	Example	Default
api_key Required \| string	The API key to manage secrets for	`abcd1234`	None

Request body application/json

Key Description Example Default

Key	Description	Example	Default
secret Required \| string	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-4PI-secret`	None

secret
Required | string

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-4PI-secret

None

View response field descriptions

Response Fields

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

Retrieve one API Secret

GET


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

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Path Parameters

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

Response Fields

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

Revoke an API Secret

DELETE


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

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Path Parameters

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

Nexmo Account API

Balance

Configuration

Secret Management

Nexmo Account API

Balance

Get Account Balance

Query Parameter

Response Fields

HTTP response 200

HTTP response 401

Top Up Account Balance

Query Parameter

Request body application/x-www-form-urlencoded

Response Fields

HTTP response 200

HTTP response 401

Configuration

Change Account Settings

Query Parameter

Request body application/x-www-form-urlencoded

Response Fields

HTTP response 200

HTTP response 401

Secret Management

Retrieve API Secrets

Authentication

Path Parameters

Response Fields

HTTP response 200

HTTP response 401

HTTP response 404

Create API Secret

Authentication

Path Parameters

Request body application/json

Response Fields

HTTP response 201

HTTP response 400

HTTP response 401

HTTP response 404

Retrieve one API Secret

Authentication

Path Parameters

Response Fields

HTTP response 200

HTTP response 401

HTTP response 404

Revoke an API Secret

Authentication

Path Parameters

HTTP response 204

HTTP response 401

HTTP response 403

HTTP response 404