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.

OpenAPI-Spezifikation herunterladen

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.

Verfügbare Operationen

Get Account Balance

Retrieve the current balance of your Vonage API account

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

Abfrage Parameter

api_key
string
Beispielabcd1234

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

api_secret
string
BeispielABCDEFGH01234abc

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

Antworten
Inhalt Typ

The current balance of your account

value
number
Beispiel10.28

The balance of the account, in EUR

autoReload
boolean

Whether the account has auto-reloading enabled

Muss eines der folgenden sein:truefalse

Beispiel Antwort

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

Abfrage Parameter

api_key
string
Beispielabcd1234

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

api_secret
string
BeispielABCDEFGH01234abc

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

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

trx
string
Erforderlich
Beispiel8ef2447e69604f642ae59363aa5f781b

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

Beispiel Anfrage

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

trx=8ef2447e69604f642ae59363aa5f781b

Antworten
Inhalt Typ

Success

error-code
Beispiel200
error-code-label
Beispielsuccess

Beispiel Antwort

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

Configuration

Manage the settings on your account

Verfügbare Operationen

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

Abfrage Parameter

api_key
string
Beispielabcd1234

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

api_secret
string
BeispielABCDEFGH01234abc

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

Anfrage Körper
Inhalt Typ
application/x-www-form-urlencoded

moCallBackUrl
string(url)
Beispielhttps://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)
Beispielhttps://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.

httpForwardMethod
string(enum)
BeispielPOST_QUERY_PARAMS

The HTTP method to use when making requests to the callback URLs.

Muss eines der folgenden sein:GET_QUERY_PARAMSPOST_QUERY_PARAMSPOST_JSON

Beispiel Anfrage

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

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

Antworten
Inhalt Typ

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

mo-callback-url
string(url)
Beispielhttps://example.com/webhooks/inbound-sms

The current or updated inbound message webhook URI

dr-callback-url
string(url)
Beispielhttps://example.com/webhooks/delivery-receipt

The current or updated delivery receipt webhook URI

max-outbound-request
integer
Beispiel30

The maximum number of outbound messages per second.

max-inbound-request
integer
Beispiel30

The maximum number of inbound messages per second.

max-calls-per-second
integer
Beispiel30

The maximum number of API calls per second.

Beispiel Antwort

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

Verfügbare Operationen

Retrieve API Secrets

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

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==`

Pfad Parameter

api_key
string
Erforderlich

The API key to manage secrets for

Antworten
Inhalt Typ
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

id
string
Beispielad6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at
string
Beispiel2017-03-02T16:34:49Z

Creation date/time for this secret

Beispiel Antwort

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

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==`

Pfad Parameter

api_key
string
Erforderlich

The API key to manage secrets for

Anfrage Körper
Inhalt Typ
application/json

secret
string
Erforderlich
Beispielexample-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

Beispiel Anfrage

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

Antworten
Inhalt Typ
application/json

Secret created

_links
object

Links related to this resource

self
object

This resource

href
string

The URI for this resource

id
string
Beispielad6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at
string
Beispiel2017-03-02T16:34:49Z

Creation date/time for this secret

Beispiel Antwort

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

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==`

Pfad Parameter

api_key
string
Erforderlich

The API key to manage secrets for

secret_id
string
Erforderlich

ID of the API Secret

Antworten
Inhalt Typ
application/json

API secret response

_links
object

Links related to this resource

self
object

This resource

href
string

The URI for this resource

id
string
Beispielad6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at
string
Beispiel2017-03-02T16:34:49Z

Creation date/time for this secret

Beispiel Antwort

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

Authentifizierung

SchlüsselBeschreibungWoBeispiel
Authorization

Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt.
Mehr lesen

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==`

Pfad Parameter

api_key
string
Erforderlich

The API key to manage secrets for

secret_id
string
Erforderlich

ID of the API Secret

Antworten

Revoked secret response (without body content)

Fehler

Im Folgenden finden Sie eine nicht erschöpfende Liste von Fehlercodes, die bei der Verwendung dieser API auftreten können.

Diese Codes gelten zusätzlich zu unseren generische Fehlercodes.

CodeInformationen
validation

Beschreibung

The provided payload is invalid

Auflösung

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

Beschreibung

You can not delete your only API secret

Auflösung

Add another API secret before deleting this one