Account API

Enables users to manage their Vonage API Account by programmable means. More information is available here: https://developer.vonage.com/.

Baixar a especificação OpenAPI

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.

Operações disponíveis

Get Account Balance

Retrieve the current balance of your Vonage API account

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Respostas
Tipo de conteúdo

The current balance of your account

Cabeçalho Parâmetros
X-Request-Id
string(uuid)
exemplof94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
value
number
exemplo10.28

The balance of the account, in EUR

autoReload
boolean

Whether the account has auto-reloading enabled

Deve ser uma das seguintes opções:truefalse

Exemplo Resposta

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/x-www-form-urlencoded

trx
string
Obrigatório
exemplo8ef2447e69604f642ae59363aa5f781b

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

Exemplo Solicitação

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

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

trx=8ef2447e69604f642ae59363aa5f781b

Respostas
Tipo de conteúdo

Success

Cabeçalho Parâmetros
X-Request-Id
string(uuid)
exemplof94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
error-code
exemplo200
error-code-label
exemplosuccess

Exemplo Resposta

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

Configuration

Manage the settings on your account

Operações disponíveis

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/x-www-form-urlencoded

moCallBackUrl
string(url)
exemplohttps://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)
exemplohttps://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)
exemploPOST_QUERY_PARAMS

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

Deve ser uma das seguintes opções:GET_QUERY_PARAMSPOST_QUERY_PARAMSPOST_JSON

Exemplo Solicitação

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
POST /account/settings HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 0

Respostas
Tipo de conteúdo

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

Cabeçalho Parâmetros
X-Request-Id
string(uuid)
exemplof94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
mo-callback-url
string(url)
exemplohttps://example.com/webhooks/inbound-sms

The current or updated inbound message webhook URI

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

The current or updated delivery receipt webhook URI

max-outbound-request
integer
exemplo30

The maximum number of outbound messages per second.

max-inbound-request
integer
exemplo30

The maximum number of inbound messages per second.

max-calls-per-second
integer
exemplo30

The maximum number of API calls per second.

Exemplo Resposta

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

Operações disponíveis

Retrieve API Secrets

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Caminho Parâmetros

api_key
string
Obrigatório

The API key to manage secrets for

Respostas
Tipo de conteúdo
application/json

The list of your current API secrets

Cabeçalho Parâmetros
X-Request-Id
string(uuid)
exemplof94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
_links
object

HAL Links object

self
object
Obrigatório

A single HAL link object

href
string
Obrigatório
exemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated
boolean

Indicates if the href is a URI template

type
string
exemploapplication/json

Media type hint for the target resource

name
string
exemploresource-name

Secondary key for selecting link objects

title
string
exemploResource Title

Human-readable title for the link

_embedded
object

The single secrets key returns an array of API secrets

secrets
array

Array of API secrets

_links
object

HAL Links object

self
object
Obrigatório

A single HAL link object

href
string
Obrigatório
exemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated
boolean

Indicates if the href is a URI template

type
string
exemploapplication/json

Media type hint for the target resource

name
string
exemploresource-name

Secondary key for selecting link objects

title
string
exemploResource Title

Human-readable title for the link

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

Secret ID

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

Creation date/time for this secret

Exemplo Resposta

{
   "_links": {
      "self": {
         "href": "https://api.vonage.com/v1/resources/abc123",
         "templated": false,
         "type": "application/json",
         "name": "resource-name",
         "title": "Resource Title"
      }
   },
   "_embedded": {
      "secrets": [
         {
            "_links": {
               "self": {
                  "href": "https://api.vonage.com/v1/resources/abc123",
                  "templated": false,
                  "type": "application/json",
                  "name": "resource-name",
                  "title": "Resource Title"
               }
            },
            "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
            "created_at": "2017-03-02T16:34:49Z"
         }
      ]
   }
}

Create API Secret

posthttps://rest.nexmo.com/accounts/:api_key/secrets

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Caminho Parâmetros

api_key
string
Obrigatório

The API key to manage secrets for

Corpo da solicitação
Tipo de conteúdo
application/json

secret
string
Obrigatório
exemploexample-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

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Secret created

Cabeçalho Parâmetros
X-Request-Id
string(uuid)
exemplof94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
_links
object

HAL Links object

self
object
Obrigatório

A single HAL link object

href
string
Obrigatório
exemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated
boolean

Indicates if the href is a URI template

type
string
exemploapplication/json

Media type hint for the target resource

name
string
exemploresource-name

Secondary key for selecting link objects

title
string
exemploResource Title

Human-readable title for the link

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

Secret ID

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

Creation date/time for this secret

Exemplo Resposta

{
   "_links": {
      "self": {
         "href": "https://api.vonage.com/v1/resources/abc123",
         "templated": false,
         "type": "application/json",
         "name": "resource-name",
         "title": "Resource Title"
      }
   },
   "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
   "created_at": "2017-03-02T16:34:49Z"
}

Retrieve one API Secret

gethttps://rest.nexmo.com/accounts/:api_key/secrets/:secret_id

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Caminho Parâmetros

api_key
string
Obrigatório

The API key to manage secrets for

secret_id
string
Obrigatório

ID of the API Secret

Respostas
Tipo de conteúdo
application/json

API secret response

Cabeçalho Parâmetros
X-Request-Id
string(uuid)
exemplof94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
_links
object

HAL Links object

self
object
Obrigatório

A single HAL link object

href
string
Obrigatório
exemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated
boolean

Indicates if the href is a URI template

type
string
exemploapplication/json

Media type hint for the target resource

name
string
exemploresource-name

Secondary key for selecting link objects

title
string
exemploResource Title

Human-readable title for the link

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

Secret ID

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

Creation date/time for this secret

Exemplo Resposta

{
   "_links": {
      "self": {
         "href": "https://api.vonage.com/v1/resources/abc123",
         "templated": false,
         "type": "application/json",
         "name": "resource-name",
         "title": "Resource Title"
      }
   },
   "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
   "created_at": "2017-03-02T16:34:49Z"
}

Revoke an API Secret

deletehttps://rest.nexmo.com/accounts/:api_key/secrets/:secret_id

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Caminho Parâmetros

api_key
string
Obrigatório

The API key to manage secrets for

secret_id
string
Obrigatório

ID of the API Secret

Respostas

Revoked secret response (without body content)

Cabeçalho Parâmetros
X-Request-Id
string(uuid)
exemplof94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging

Erros

A seguir, apresentamos uma lista não exaustiva de códigos de erro que podem ocorrer durante o uso desta API.

Esses códigos são adicionais aos que constam em nosso site códigos de erro genéricos.

CódigoInformações
validation

Descrição

The provided payload is invalid

Resolução

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

Descrição

You can not delete your only API secret

Resolução

Add another API secret before deleting this one