Subaccounts API

The Nexmo 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.

Subaccount Management

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

Create subaccount

Create a subaccount for a given primary account.

POST https://api.nexmo.com/accounts/:api_key/subaccounts

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account

None None

Request body application/json

Key Description Example Default
name
Required | string

None

Subaccount department A None
use_primary_account_balance
boolean

None

None None

View response field descriptions

Response Fields

Field Description
secret
string

API secret of the subaccount.

api_key
string

Unique subaccount ID.

name
string

Name of the subaccount.

primary_account_api_key
string

Unique primary account ID.

use_primary_account_balance
boolean

Flag showing if balance is shared with primary account.

created_at
string

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number

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

credit_limit
number

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

{
  "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
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/account/subaccounts#validation",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "invalid_parameters": [
    {
      "name": "use_primary_account_balance",
      "reason": "Should be either 'true' or 'false'"
    }
  ],
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}

Retrieve list of subaccounts

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

GET https://api.nexmo.com/accounts/:api_key/subaccounts

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account

None None

View response field descriptions

Response Fields

Field Description
_embedded
object
Field Description
primary_account
Field Description
api_key
string

Unique subaccount ID.

name
string

Name of the subaccount.

primary_account_api_key
string

Unique primary account ID.

use_primary_account_balance
boolean

Flag showing if balance is shared with primary account.

created_at
string

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number

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

credit_limit
number

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

subaccounts
array of s
Field Description
api_key
string

Unique subaccount ID.

name
string

Name of the subaccount.

primary_account_api_key
string

Unique primary account ID.

use_primary_account_balance
boolean

Flag showing if balance is shared with primary account.

created_at
string

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number

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

credit_limit
number

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

{
  "_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
      }
    ]
  }
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}

Retrieve a subaccount

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

GET https://api.nexmo.com/accounts/:api_key/subaccounts/:subaccount_key

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account

None None
subaccount_key
Required | string

ID of the subaccount

None None

View response field descriptions

Response Fields

Field Description
api_key
string

Unique subaccount ID.

name
string

Name of the subaccount.

primary_account_api_key
string

Unique primary account ID.

use_primary_account_balance
boolean

Flag showing if balance is shared with primary account.

created_at
string

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number

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

credit_limit
number

Credit limit of the subAccount. Value is null if balance is shared with 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
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}

Modify a subaccount

Change one or more properties of a subaccount.

PATCH https://api.nexmo.com/accounts/:api_key/subaccounts/:subaccount_key

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account

None None
subaccount_key
Required | string

ID of the subaccount

None None

Request body application/json

Key Description Example Default
suspended
boolean

None

true None
use_primary_account_balance
boolean

None

None None

View response field descriptions

Response Fields

Field Description
api_key
string

Unique subaccount ID.

name
string

Name of the subaccount.

primary_account_api_key
string

Unique primary account ID.

use_primary_account_balance
boolean

Flag showing if balance is shared with primary account.

created_at
string

Subaccount creation date and time.

suspended
boolean

Subaccount suspension status.

balance
number

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

credit_limit
number

Credit limit of the subAccount. Value is null if balance is shared with 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
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/account/subaccounts#validation",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "invalid_parameters": [
    {
      "name": "use_primary_account_balance",
      "reason": "Should be either 'true' or 'false'"
    }
  ],
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}

Transfers

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

Transfer credit

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

POST https://api.nexmo.com/accounts/:api_key/credit-transfers

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account

None None

Request body application/json

Key Description Example Default
from
Required | string

None

7c9738e6 None
to
Required | string

None

ad6dc56f None
amount
Required | number

None

123.45 None
reference
string

None

This gets added to the audit log None

View response field descriptions

Response Fields

Field Description
credit_transfer_id
string

Unique credit transfer ID

amount
number

Credit transfer amount

from
string

Account the credit is transferred from

to
string

Account the credit is transferred to

reference
string

Reference for the credit transfer

created_at
string

The date and time when the credit transfer was executed

{
  "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"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/account/subaccounts#validation",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "invalid_parameters": [
    {
      "name": "use_primary_account_balance",
      "reason": "Should be either 'true' or 'false'"
    }
  ],
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}

Retrieve list of credit transfers

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

GET https://api.nexmo.com/accounts/:api_key/credit-transfers

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account.

None None

Query Parameter

Key Description Example Default
start_date
Required | string

Start of the retrieval period.

2019-07-15T13:11:44Z None
end_date
string

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

2019-07-15T14:11:44Z None
subaccount
string

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

None None

View response field descriptions

Response Fields

Field Description
_embedded
object
Field Description
credit-transfers
array of s
Field Description
credit_transfer_id
string

Unique credit transfer ID

amount
number

Credit transfer amount

from
string

Account the credit is transferred from

to
string

Account the credit is transferred to

reference
string

Reference for the credit transfer

created_at
string

The date and time when the credit transfer was executed

{
  "_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"
      }
    ]
  }
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}

Transfer balance

Transfer positive balance between a primary account and one of its subaccounts. Note that this will only work if the source account has a positive balance!

POST https://api.nexmo.com/accounts/:api_key/balance-transfers

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account

None None

Request body application/json

Key Description Example Default
from
Required | string

None

7c9738e6 None
to
Required | string

None

ad6dc56f None
amount
Required | number

None

123.45 None
reference
string

None

This gets added to the audit log None

View response field descriptions

Response Fields

Field Description
balance_transfer_id
string

Unique balance transfer ID

amount
number

Balance transfer amount

from
string

Account the balance is transferred from

to
string

Account the balance is transferred to

reference
string

Reference for the balance transfer

created_at
string

The date and time when the balance transfer was executed

{
  "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"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/account/subaccounts#validation",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "invalid_parameters": [
    {
      "name": "use_primary_account_balance",
      "reason": "Should be either 'true' or 'false'"
    }
  ],
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}

Retrieve list of balance transfers

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

GET https://api.nexmo.com/accounts/:api_key/balance-transfers

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

ID of the primary account.

None None

Query Parameter

Key Description Example Default
start_date
Required | string

Start of the retrieval period.

2019-07-15T13:11:44Z None
end_date
string

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

2019-07-15T14:11:44Z None
subaccount
string

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

None None

View response field descriptions

Response Fields

Field Description
_embedded
object
Field Description
balance_transfers
array of s
Field Description
balance_transfer_id
string

Unique balance transfer ID

amount
number

Balance transfer amount

from
string

Account the balance is transferred from

to
string

Account the balance is transferred to

reference
string

Reference for the balance transfer

created_at
string

The date and time when the balance transfer was executed

{
  "_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"
      }
    ]
  }
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials",
  "instance": "798b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unprovisioned",
  "title": "Authorisation error",
  "detail": "Account acc6111f is not provisioned to access Subaccount Provisioning API",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'acc6111f' does not exist, or you do not have access",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}