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 OAS 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

Host


        https://rest.nexmo.com

GET


        /account/get-balance

Query Parameter

api_key

string | Required

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

api_secret

string | Required

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

Responses

200 The current balance of your account

value

number

The balance of the account, in EUR

autoReload

boolean

Whether the account has auto-reloading enabled

One of: true or false

value

number

The balance of the account, in EUR

autoReload

boolean

Whether the account has auto-reloading enabled

One of: true or false

Example Responses

200 401

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

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

Host


        https://rest.nexmo.com

POST


        /account/top-up

Query Parameter

api_key

string | Required

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

api_secret

string | Required

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

Request body application/x-www-form-urlencoded

trx

string | Required

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

Responses

200 Success

error-code

error-code-label

error-code

error-code-label

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

Example Responses

200 401

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

Configuration

Manage the settings on your account

Available Operations:

post Change Account Settings

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

Host


        https://rest.nexmo.com

POST


        /account/settings

Query Parameter

api_key

string | Required

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

api_secret

string | Required

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

Request body application/x-www-form-urlencoded

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.

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.

Responses

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

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

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.

Example Request

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

Example Responses

200 401

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

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.

Available Operations:

get Retrieve API Secrets
post Create API Secret
get Retrieve one API Secret
delete Revoke an API Secret

Retrieve API Secrets

GET


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

Host


        https://api.nexmo.com

GET


        /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

api_key

string | Required

The API key to manage secrets for

Responses

200 The list of your current API secrets

_embedded

object

The single secrets key returns an array of API secrets

array of objects

Array of API secrets

string

Secret ID

string

Creation date/time for this secret

This endpoint does not support application/xml

Example Responses

200 401 404

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

Create API Secret

POST


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

Host


        https://api.nexmo.com

POST


        /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

api_key

string | Required

The API key to manage secrets for

Request body application/json

secret

string | Required

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

Responses

201 Secret created

id

string

Secret ID

created_at

string

Creation date/time for this secret

This endpoint does not support application/xml

Example Request

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

Example Responses

201 400 401 404

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

Retrieve one API Secret

GET


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

Host


        https://api.nexmo.com

GET


        /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

api_key

string | Required

The API key to manage secrets for

secret_id

string | Required

ID of the API Secret

Responses

200 API secret response

id

string

Secret ID

created_at

string

Creation date/time for this secret

This endpoint does not support application/xml

Example Responses

200 401 404

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

Revoke an API Secret

DELETE


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

Host


        https://api.nexmo.com

DELETE


        /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

api_key

string | Required

The API key to manage secrets for

secret_id

string | Required

ID of the API Secret

Example Responses

204 401 403 404

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