Account API

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

Descargar la especificación 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.

Operaciones disponibles

Get Account Balance

Retrieve the current balance of your Vonage API account

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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Consulta Parámetros

api_key

string

ejemploabcd1234

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

api_secret

string

ejemploABCDEFGH01234abc

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

Respuestas
Tipo de contenido
application/json

The current balance of your account

Cabecera Parámetros

X-Request-Id

string(uuid)

ejemplof94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

value

number

ejemplo10.28

The balance of the account, in EUR

autoReload

boolean

Whether the account has auto-reloading enabled

Debe ser uno de:truefalse

Ejemplo Respuesta

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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Consulta Parámetros

api_key

string

ejemploabcd1234

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

api_secret

string

ejemploABCDEFGH01234abc

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

Cuerpo de la solicitud
Tipo de contenido
application/x-www-form-urlencoded

trx

string

Requerido

ejemplo8ef2447e69604f642ae59363aa5f781b

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

Ejemplo Solicitar

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

Respuestas
Tipo de contenido
application/json

Success

Cabecera Parámetros

X-Request-Id

string(uuid)

ejemplof94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

error-code

ejemplo200

error-code-label

ejemplosuccess

Ejemplo Respuesta

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

Configuration

Manage the settings on your account

Operaciones disponibles

Change Account Settings

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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Consulta Parámetros

api_key

string

ejemploabcd1234

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

api_secret

string

ejemploABCDEFGH01234abc

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

Cuerpo de la solicitud
Tipo de contenido
application/x-www-form-urlencoded

moCallBackUrl

string(url)

ejemplohttps://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)

ejemplohttps://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)

ejemploPOST_QUERY_PARAMS

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

Debe ser uno de:GET_QUERY_PARAMSPOST_QUERY_PARAMSPOST_JSON

Ejemplo Solicitar

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: 150

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

Respuestas
Tipo de contenido
application/json

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

Cabecera Parámetros

X-Request-Id

string(uuid)

ejemplof94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

mo-callback-url

string(url)

ejemplohttps://example.com/webhooks/inbound-sms

The current or updated inbound message webhook URI

dr-callback-url

string(url)

ejemplohttps://example.com/webhooks/delivery-receipt

The current or updated delivery receipt webhook URI

max-outbound-request

integer

ejemplo30

The maximum number of outbound messages per second.

max-inbound-request

integer

ejemplo30

The maximum number of inbound messages per second.

max-calls-per-second

integer

ejemplo30

The maximum number of API calls per second.

Ejemplo Respuesta

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

Operaciones disponibles

Retrieve API Secrets

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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Ruta Parámetros

api_key

string

Requerido

The API key to manage secrets for

Respuestas
Tipo de contenido
application/json

The list of your current API secrets

Cabecera Parámetros

X-Request-Id

string(uuid)

ejemplof94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

_links

object

HAL Links object

self

object

Requerido

A single HAL link object

href

string

Requerido

ejemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

ejemploapplication/json

Media type hint for the target resource

name

string

ejemploresource-name

Secondary key for selecting link objects

title

string

ejemploResource 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

Requerido

A single HAL link object

href

string

Requerido

ejemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

ejemploapplication/json

Media type hint for the target resource

name

string

ejemploresource-name

Secondary key for selecting link objects

title

string

ejemploResource Title

Human-readable title for the link

string

ejempload6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at

string

ejemplo2017-03-02T16:34:49Z

Creation date/time for this secret

Ejemplo Respuesta

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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Ruta Parámetros

api_key

string

Requerido

The API key to manage secrets for

Cuerpo de la solicitud
Tipo de contenido
application/json

secret

string

Requerido

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

Ejemplo Solicitar

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

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

Respuestas
Tipo de contenido
application/json

Secret created

Cabecera Parámetros

X-Request-Id

string(uuid)

ejemplof94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

_links

object

HAL Links object

self

object

Requerido

A single HAL link object

href

string

Requerido

ejemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

ejemploapplication/json

Media type hint for the target resource

name

string

ejemploresource-name

Secondary key for selecting link objects

title

string

ejemploResource Title

Human-readable title for the link

string

ejempload6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at

string

ejemplo2017-03-02T16:34:49Z

Creation date/time for this secret

Ejemplo Respuesta

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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Ruta Parámetros

api_key

string

Requerido

The API key to manage secrets for

secret_id

string

Requerido

ID of the API Secret

Respuestas
Tipo de contenido
application/json

API secret response

Cabecera Parámetros

X-Request-Id

string(uuid)

ejemplof94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

_links

object

HAL Links object

self

object

Requerido

A single HAL link object

href

string

Requerido

ejemplohttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

ejemploapplication/json

Media type hint for the target resource

name

string

ejemploresource-name

Secondary key for selecting link objects

title

string

ejemploResource Title

Human-readable title for the link

string

ejempload6dc56f-07b5-46e1-a527-85530e625800

Secret ID

created_at

string

ejemplo2017-03-02T16:34:49Z

Creation date/time for this secret

Ejemplo Respuesta

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

Autenticación

Clave	Descripción	Dónde	Ejemplo
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Ruta Parámetros

api_key

string

Requerido

The API key to manage secrets for

secret_id

string

Requerido

ID of the API Secret

Respuestas

Revoked secret response (without body content)

Cabecera Parámetros

X-Request-Id

string(uuid)

ejemplof94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

Errores

La siguiente es una lista no exhaustiva de códigos de error que pueden producirse al utilizar esta API.

Estos códigos se suman a cualquiera de nuestros códigos de error genéricos.

Código	Información
validation	Descripción The provided payload is invalid Resolución 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	Descripción You can not delete your only API secret Resolución Add another API secret before deleting this one

Código

Información

validation

Descripción

The provided payload is invalid

Resolución

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

Descripción

You can not delete your only API secret

Resolución

Add another API secret before deleting this one

Account API

Balance

Operaciones disponibles

Get Account Balance

Autenticación

Consulta Parámetros

Respuestas Tipo de contenidoapplication/json

Cabecera Parámetros

Ejemplo Respuesta

Top Up Account Balance

Autenticación

Consulta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/x-www-form-urlencoded

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Cabecera Parámetros

Ejemplo Respuesta

Configuration

Operaciones disponibles

Change Account Settings

Autenticación

Consulta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/x-www-form-urlencoded

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Cabecera Parámetros

Ejemplo Respuesta

Secret Management

Operaciones disponibles

Autenticación

Ruta Parámetros

Respuestas Tipo de contenidoapplication/json

Cabecera Parámetros

Ejemplo Respuesta

Autenticación

Ruta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Cabecera Parámetros

Ejemplo Respuesta

Autenticación

Ruta Parámetros

Respuestas Tipo de contenidoapplication/json

Cabecera Parámetros

Ejemplo Respuesta

Autenticación

Ruta Parámetros

Respuestas

Cabecera Parámetros

Errores

Respuestas
Tipo de contenido
application/json

Cuerpo de la solicitud
Tipo de contenido
application/x-www-form-urlencoded

Respuestas
Tipo de contenido
application/json

Cuerpo de la solicitud
Tipo de contenido
application/x-www-form-urlencoded

Respuestas
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/json

Cuerpo de la solicitud
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/json