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.

Baixar a especificação OpenAPI

Subaccount Management

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

Operações disponíveis

Retrieve list of subaccounts

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

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

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

ID of the primary account

Respostas
Tipo de conteúdo
application/json

Subaccounts response

_embedded
object
primary_account
api_key
string
exemplobbe6222f

Unique subaccount ID.

name
string
exemploSubaccount department A

Name of the subaccount.

primary_account_api_key
string
exemploacc6111f

Unique primary account ID.

use_primary_account_balance
boolean
exemplotrue

Flag showing if balance is shared with primary account.

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

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number
exemplo100.25

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

credit_limit
number
exemplo-100.25

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

subaccounts
array
api_key
string
exemplobbe6222f

Unique subaccount ID.

name
string
exemploSubaccount department A

Name of the subaccount.

primary_account_api_key
string
exemploacc6111f

Unique primary account ID.

use_primary_account_balance
boolean
exemplotrue

Flag showing if balance is shared with primary account.

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

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number
exemplo100.25

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

credit_limit
number
exemplo-100.25

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

Exemplo Resposta

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

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

ID of the primary account

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

name
string
Obrigatório
Max80
exemploSubaccount department A
secret
string
exemploPassword123
use_primary_account_balance
boolean
Padrãotrue

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Subaccount response

secret
string
exemploPassword123

API secret of the subaccount.

api_key
string
exemplobbe6222f

Unique subaccount ID.

name
string
exemploSubaccount department A

Name of the subaccount.

primary_account_api_key
string
exemploacc6111f

Unique primary account ID.

use_primary_account_balance
boolean
exemplotrue

Flag showing if balance is shared with primary account.

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

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number
exemplo100.25

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

credit_limit
number
exemplo-100.25

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

Exemplo Resposta

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

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

ID of the primary account

subaccount_key
string
Obrigatório

ID of the subaccount

Respostas
Tipo de conteúdo
application/json

Subaccount response

api_key
string
exemplobbe6222f

Unique subaccount ID.

name
string
exemploSubaccount department A

Name of the subaccount.

primary_account_api_key
string
exemploacc6111f

Unique primary account ID.

use_primary_account_balance
boolean
exemplotrue

Flag showing if balance is shared with primary account.

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

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number
exemplo100.25

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

credit_limit
number
exemplo-100.25

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

Exemplo Resposta

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

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

ID of the primary account

subaccount_key
string
Obrigatório

ID of the subaccount

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

suspended
boolean
exemplotrue
use_primary_account_balance
boolean
name
string
exemploSubaccount department B

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Subaccount response

api_key
string
exemplobbe6222f

Unique subaccount ID.

name
string
exemploSubaccount department A

Name of the subaccount.

primary_account_api_key
string
exemploacc6111f

Unique primary account ID.

use_primary_account_balance
boolean
exemplotrue

Flag showing if balance is shared with primary account.

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

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number
exemplo100.25

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

credit_limit
number
exemplo-100.25

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

Exemplo Resposta

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

Operações disponíveis

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

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

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

Respostas
Tipo de conteúdo
application/json

List credit transfers response

_embedded
object
credit-transfers
array
credit_transfer_id
string
exemplo07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount
number
exemplo123.45

Credit transfer amount

from
string
exemplo7c9738e6

Account the credit is transferred from

to
string
exempload6dc56f

Account the credit is transferred to

reference
string
exemploThis gets added to the audit log

Reference for the credit transfer

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

The date and time when the credit transfer was executed

Exemplo Resposta

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

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

ID of the primary account

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

from
string
Obrigatório
exemplo7c9738e6
to
string
Obrigatório
exempload6dc56f
amount
number
Obrigatório
exemplo123.45
reference
string
exemploThis gets added to the audit log

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Credit transfer response

credit_transfer_id
string
exemplo07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount
number
exemplo123.45

Credit transfer amount

from
string
exemplo7c9738e6

Account the credit is transferred from

to
string
exempload6dc56f

Account the credit is transferred to

reference
string
exemploThis gets added to the audit log

Reference for the credit transfer

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

The date and time when the credit transfer was executed

Exemplo Resposta

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

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

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

Respostas
Tipo de conteúdo
application/json

List balance transfers response

_embedded
object
balance_transfers
array
balance_transfer_id
string
exemplo07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount
number
exemplo123.45

Balance transfer amount

from
string
exemplo7c9738e6

Account the balance is transferred from

to
string
exempload6dc56f

Account the balance is transferred to

reference
string
exemploThis gets added to the audit log

Reference for the balance transfer

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

The date and time when the balance transfer was executed

Exemplo Resposta

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

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

ID of the primary account

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

from
string
Obrigatório
exemplo7c9738e6
to
string
Obrigatório
exempload6dc56f
amount
number
Obrigatório
exemplo123.45
reference
string
exemploThis gets added to the audit log

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Balance transfer response

balance_transfer_id
string
exemplo07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount
number
exemplo123.45

Balance transfer amount

from
string
exemplo7c9738e6

Account the balance is transferred from

to
string
exempload6dc56f

Account the balance is transferred to

reference
string
exemploThis gets added to the audit log

Reference for the balance transfer

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

The date and time when the balance transfer was executed

Exemplo Resposta

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

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

ID of the primary account.

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

from
string
exemplo7c9738e6
to
string
exempload6dc56f
number
number
exemplo23507703696
country
string
exemploGB

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Number transfer response

number
string
exemplo235077036

Number transfered

country
string
exemploGB

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

from
string
exemplo7c9738e6

Account the number is transferred from

to
string
exempload6dc56f

Account the number is transferred to

Exemplo Resposta

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

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 request failed due to validation errors

Resolução

See the detail (and, if present, the invalid_parameters) fields for the exact reason this request was rejected and review the documentation.

invalid-transfers

Descrição

Invalid transfer

Resolução

See the detail field for the reason this transfer is invalid.

provisioning

Descrição

Maximum number of sub-accounts reached

Resolução

If you need more subaccounts, contact Vonage Support.

internal-error

Descrição

An error has occurred in the platform while processing this request

Resolução

If the error persists, contact Vonage Support.

invalid-number-transfer

Descrição

Failed to perform transfer number from source account to destination account

Resolução

See the detail field for the reason this transfer is invalid.

missing-number-transfer

Descrição

Could not transfer number from source account to destination account - ShortCode not found

Resolução

See the detail field for the reason this transfer is invalid.

transfer-conflict

Descrição

Could not transfer number from source account to destination account - ShortCode is already owned by requesting account

Resolução

See the detail field for the reason this transfer is invalid.