Subaccounts API

The Subaccounts API enables you to create subaccounts under your primary account. Subaccounts facilitate differential product configuration, reporting, and billing. The Subaccounts API is released initially with restricted availability. You can read more about the API in the Subaccounts documentation.

Descargar la especificación OpenAPI

Subaccount Management

This section shows how you can create, retrieve and modify subaccounts of a primary account.

Operaciones disponibles

Retrieve list of subaccounts

Get the information of all the subaccounts owned by the primary account.

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

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

ID of the primary account

Respuestas
Tipo de contenido
application/json

Subaccounts response

_embedded

object

primary_account

api_key

string

ejemplobbe6222f

Unique subaccount ID.

name

string

ejemploSubaccount department A

Name of the subaccount.

primary_account_api_key

string

ejemploacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

ejemplotrue

Flag showing if balance is shared with primary account.

created_at

string

ejemplo2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

ejemplo100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

ejemplo-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

subaccounts

array

api_key

string

ejemplobbe6222f

Unique subaccount ID.

name

string

ejemploSubaccount department A

Name of the subaccount.

primary_account_api_key

string

ejemploacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

ejemplotrue

Flag showing if balance is shared with primary account.

created_at

string

ejemplo2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

ejemplo100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

ejemplo-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Ejemplo Respuesta

{
   "_embedded": {
      "primary_account": {
         "api_key": "bbe6222f",
         "name": "Subaccount department A",
         "primary_account_api_key": "acc6111f",
         "use_primary_account_balance": true,
         "created_at": "2018-03-02T16:34:49Z",
         "suspended": false,
         "balance": 100.25,
         "credit_limit": -100.25
      },
      "subaccounts": [
         {
            "api_key": "bbe6222f",
            "name": "Subaccount department A",
            "primary_account_api_key": "acc6111f",
            "use_primary_account_balance": true,
            "created_at": "2018-03-02T16:34:49Z",
            "suspended": false,
            "balance": 100.25,
            "credit_limit": -100.25
         }
      ]
   }
}

Create subaccount

Create a subaccount for a given primary account.

posthttps://api.nexmo.com/accounts/:api_key/subaccounts

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

ID of the primary account

Cuerpo de la solicitud
Tipo de contenido
application/json

name

string

Requerido

Max80

ejemploSubaccount department A

secret

string

ejemploPassword123

use_primary_account_balance

boolean

Por defectotrue

Ejemplo Solicitar

{
   "name": "Subaccount department A",
   "secret": "Password123",
   "use_primary_account_balance": false
}

{
   "name": "Subaccount department A",
   "secret": "Password123",
   "use_primary_account_balance": false
}

Respuestas
Tipo de contenido
application/json

Subaccount response

secret

string

ejemploPassword123

API secret of the subaccount.

api_key

string

ejemplobbe6222f

Unique subaccount ID.

name

string

ejemploSubaccount department A

Name of the subaccount.

primary_account_api_key

string

ejemploacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

ejemplotrue

Flag showing if balance is shared with primary account.

created_at

string

ejemplo2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

ejemplo100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

ejemplo-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Ejemplo Respuesta

{
   "secret": "Password123",
   "api_key": "bbe6222f",
   "name": "Subaccount department A",
   "primary_account_api_key": "acc6111f",
   "use_primary_account_balance": true,
   "created_at": "2018-03-02T16:34:49Z",
   "suspended": false,
   "balance": 100.25,
   "credit_limit": -100.25
}

Retrieve a subaccount

Get the information of a subaccount specified with its API key.

gethttps://api.nexmo.com/accounts/:api_key/subaccounts/:subaccount_key

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

ID of the primary account

subaccount_key

string

Requerido

ID of the subaccount

Respuestas
Tipo de contenido
application/json

Subaccount response

api_key

string

ejemplobbe6222f

Unique subaccount ID.

name

string

ejemploSubaccount department A

Name of the subaccount.

primary_account_api_key

string

ejemploacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

ejemplotrue

Flag showing if balance is shared with primary account.

created_at

string

ejemplo2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

ejemplo100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

ejemplo-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Ejemplo Respuesta

{
   "api_key": "bbe6222f",
   "name": "Subaccount department A",
   "primary_account_api_key": "acc6111f",
   "use_primary_account_balance": true,
   "created_at": "2018-03-02T16:34:49Z",
   "suspended": false,
   "balance": 100.25,
   "credit_limit": -100.25
}

Modify a subaccount

Change one or more properties of a subaccount.

patchhttps://api.nexmo.com/accounts/:api_key/subaccounts/:subaccount_key

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

ID of the primary account

subaccount_key

string

Requerido

ID of the subaccount

Cuerpo de la solicitud
Tipo de contenido
application/json

suspended

boolean

ejemplotrue

use_primary_account_balance

boolean

name

string

ejemploSubaccount department B

Ejemplo Solicitar

{
   "suspended": true,
   "use_primary_account_balance": false,
   "name": "Subaccount department B"
}

{
   "suspended": true,
   "use_primary_account_balance": false,
   "name": "Subaccount department B"
}

Respuestas
Tipo de contenido
application/json

Subaccount response

api_key

string

ejemplobbe6222f

Unique subaccount ID.

name

string

ejemploSubaccount department A

Name of the subaccount.

primary_account_api_key

string

ejemploacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

ejemplotrue

Flag showing if balance is shared with primary account.

created_at

string

ejemplo2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

ejemplo100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

ejemplo-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Ejemplo Respuesta

{
   "api_key": "bbe6222f",
   "name": "Subaccount department A",
   "primary_account_api_key": "acc6111f",
   "use_primary_account_balance": true,
   "created_at": "2018-03-02T16:34:49Z",
   "suspended": false,
   "balance": 100.25,
   "credit_limit": -100.25
}

Transfers

This section shows how you execute credit, balance and number transfers, as well as viewing past transactions.

Operaciones disponibles

Retrieve list of credit transfers

Retrieve a list of credit transfers that have taken place for a primary account within a specified time period.

gethttps://api.nexmo.com/accounts/:api_key/credit-transfers

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

ID of the primary account.

Consulta Parámetros

start_date

string

Start of the retrieval period.

end_date

string

End of the retrieval period. If absent then all transfers until now is returned.

subaccount

string

Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts

Respuestas
Tipo de contenido
application/json

List credit transfers response

_embedded

object

credit-transfers

array

credit_transfer_id

string

ejemplo07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

ejemplo123.45

Credit transfer amount

from

string

ejemplo7c9738e6

Account the credit is transferred from

string

ejempload6dc56f

Account the credit is transferred to

reference

string

ejemploThis gets added to the audit log

Reference for the credit transfer

created_at

string

ejemplo2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Ejemplo Respuesta

{
   "_embedded": {
      "credit-transfers": [
         {
            "credit_transfer_id": "07b5-46e1-a527-85530e625800",
            "amount": 123.45,
            "from": "7c9738e6",
            "to": "ad6dc56f",
            "reference": "This gets added to the audit log",
            "created_at": "2019-03-02T16:34:49Z"
         }
      ]
   }
}

Transfer credit

Transfer credit limit between a primary account and one of its subaccounts.

posthttps://api.nexmo.com/accounts/:api_key/credit-transfers

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

ID of the primary account

Cuerpo de la solicitud
Tipo de contenido
application/json

from

string

Requerido

ejemplo7c9738e6

string

Requerido

ejempload6dc56f

amount

number

Requerido

ejemplo123.45

reference

string

ejemploThis gets added to the audit log

Ejemplo Solicitar

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

Respuestas
Tipo de contenido
application/json

Credit transfer response

credit_transfer_id

string

ejemplo07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

ejemplo123.45

Credit transfer amount

from

string

ejemplo7c9738e6

Account the credit is transferred from

string

ejempload6dc56f

Account the credit is transferred to

reference

string

ejemploThis gets added to the audit log

Reference for the credit transfer

created_at

string

ejemplo2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Ejemplo Respuesta

{
   "credit_transfer_id": "07b5-46e1-a527-85530e625800",
   "amount": 123.45,
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "reference": "This gets added to the audit log",
   "created_at": "2019-03-02T16:34:49Z"
}

Retrieve list of balance transfers

Retrieve a list of balance transfers that have taken place for a primary account within a specified time period.

gethttps://api.nexmo.com/accounts/:api_key/balance-transfers

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

ID of the primary account.

Consulta Parámetros

start_date

string

Start of the retrieval period.

end_date

string

End of the retrieval period. If absent then all transfers until now is returned.

subaccount

string

Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts

Respuestas
Tipo de contenido
application/json

List balance transfers response

_embedded

object

balance_transfers

array

balance_transfer_id

string

ejemplo07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

ejemplo123.45

Balance transfer amount

from

string

ejemplo7c9738e6

Account the balance is transferred from

string

ejempload6dc56f

Account the balance is transferred to

reference

string

ejemploThis gets added to the audit log

Reference for the balance transfer

created_at

string

ejemplo2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Ejemplo Respuesta

{
   "_embedded": {
      "balance_transfers": [
         {
            "balance_transfer_id": "07b5-46e1-a527-85530e625800",
            "amount": 123.45,
            "from": "7c9738e6",
            "to": "ad6dc56f",
            "reference": "This gets added to the audit log",
            "created_at": "2019-03-02T16:34:49Z"
         }
      ]
   }
}

Transfer balance

Transfer balance between a primary account and one of its subaccounts. Note that balance_available_for_transfer = |account_balance - credit_limit| of the source account.

posthttps://api.nexmo.com/accounts/:api_key/balance-transfers

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

ID of the primary account

Cuerpo de la solicitud
Tipo de contenido
application/json

from

string

Requerido

ejemplo7c9738e6

string

Requerido

ejempload6dc56f

amount

number

Requerido

ejemplo123.45

reference

string

ejemploThis gets added to the audit log

Ejemplo Solicitar

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

Respuestas
Tipo de contenido
application/json

Balance transfer response

balance_transfer_id

string

ejemplo07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

ejemplo123.45

Balance transfer amount

from

string

ejemplo7c9738e6

Account the balance is transferred from

string

ejempload6dc56f

Account the balance is transferred to

reference

string

ejemploThis gets added to the audit log

Reference for the balance transfer

created_at

string

ejemplo2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Ejemplo Respuesta

{
   "balance_transfer_id": "07b5-46e1-a527-85530e625800",
   "amount": 123.45,
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "reference": "This gets added to the audit log",
   "created_at": "2019-03-02T16:34:49Z"
}

Transfer number

Transfer number from one account to another.

posthttps://api.nexmo.com/accounts/:api_key/transfer-number

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

ID of the primary account.

Cuerpo de la solicitud
Tipo de contenido
application/json

from

string

ejemplo7c9738e6

string

ejempload6dc56f

number

ejemplo23507703696

country

string

ejemploGB

Ejemplo Solicitar

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "number": "23507703696",
   "country": "GB"
}

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "number": "23507703696",
   "country": "GB"
}

Respuestas
Tipo de contenido
application/json

Number transfer response

number

string

ejemplo235077036

Number transfered

country

string

ejemploGB

The two character country code in ISO 3166-1 alpha-2 format

from

string

ejemplo7c9738e6

Account the number is transferred from

string

ejempload6dc56f

Account the number is transferred to

Ejemplo Respuesta

{
   "number": "235077036",
   "country": "GB",
   "from": "7c9738e6",
   "to": "ad6dc56f"
}

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 request failed due to validation errors Resolución See the `detail` (and, if present, the `invalid_parameters`) fields for the exact reason this request was rejected and review the documentation.
invalid-transfers	Descripción Invalid transfer Resolución See the `detail` field for the reason this transfer is invalid.
provisioning	Descripción Maximum number of sub-accounts reached Resolución If you need more subaccounts, contact Vonage Support.
internal-error	Descripción An error has occurred in the platform while processing this request Resolución If the error persists, contact Vonage Support.
invalid-number-transfer	Descripción Failed to perform transfer number from source account to destination account Resolución See the `detail` field for the reason this transfer is invalid.
missing-number-transfer	Descripción Could not transfer number from source account to destination account - ShortCode not found Resolución See the `detail` field for the reason this transfer is invalid.
transfer-conflict	Descripción Could not transfer number from source account to destination account - ShortCode is already owned by requesting account Resolución See the `detail` field for the reason this transfer is invalid.

Subaccounts API

Subaccount Management

Operaciones disponibles

Retrieve list of subaccounts

Autenticación

Ruta Parámetros

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Create subaccount

Autenticación

Ruta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Retrieve a subaccount

Autenticación

Ruta Parámetros

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Modify a subaccount

Autenticación

Ruta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Transfers

Operaciones disponibles

Retrieve list of credit transfers

Autenticación

Ruta Parámetros

Consulta Parámetros

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Transfer credit

Autenticación

Ruta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Retrieve list of balance transfers

Autenticación

Ruta Parámetros

Consulta Parámetros

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Transfer balance

Autenticación

Ruta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Transfer number

Autenticación

Ruta Parámetros

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Errores

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

Cuerpo de la solicitud
Tipo de contenido
application/json

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

Cuerpo de la solicitud
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