Subaccount Management Transfers
 
 

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.

Available Operations:

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
Host https://api.nexmo.com
GET /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

api_key
string | Required

ID of the primary account

Responses

200 Subaccounts response
_embedded
object
primary_account
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
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.

Example Responses

200 401 403 404
{
  "_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"
}

Create subaccount

Create a subaccount for a given primary account.

POST https://api.nexmo.com/accounts/:api_key/subaccounts
Host https://api.nexmo.com
POST /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

api_key
string | Required

ID of the primary account

Request body application/json

name
string | Required
secret
string
use_primary_account_balance
boolean

Responses

200 Subaccount response
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.

Example Request

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

Example Responses

200 401 403 404 422
{
  "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 a subaccount

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

GET https://api.nexmo.com/accounts/:api_key/subaccounts/:subaccount_key
Host https://api.nexmo.com
GET /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

api_key
string | Required

ID of the primary account

subaccount_key
string | Required

ID of the subaccount

Responses

200 Subaccount response
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.

Example Responses

200 401 403 404
{
  "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
Host https://api.nexmo.com
PATCH /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

api_key
string | Required

ID of the primary account

subaccount_key
string | Required

ID of the subaccount

Request body application/json

suspended
boolean
use_primary_account_balance
boolean

Responses

200 Subaccount response
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.

Example Request

{
  "suspended": true
}

Example Responses

200 401 403 404 422
{
  "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.

Available Operations:

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
Host https://api.nexmo.com
GET /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

api_key
string | Required

ID of the primary account.

Query Parameter

start_date
string | Required

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

Responses

200 List credit transfers response
_embedded
object
credit-transfers
array
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

Example Responses

200 401 403 404
{
  "_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 credit

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

POST https://api.nexmo.com/accounts/:api_key/credit-transfers
Host https://api.nexmo.com
POST /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

api_key
string | Required

ID of the primary account

Request body application/json

from
string | Required
to
string | Required
amount
number | Required
reference
string

Responses

200 Credit transfer response
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

Example Request

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

Example Responses

200 401 403 404 422
{
  "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 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
Host https://api.nexmo.com
GET /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

api_key
string | Required

ID of the primary account.

Query Parameter

start_date
string | Required

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

Responses

200 List balance transfers response
_embedded
object
balance_transfers
array
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

Example Responses

200 401 403 404
{
  "_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"
}

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.

POST https://api.nexmo.com/accounts/:api_key/balance-transfers
Host https://api.nexmo.com
POST /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

api_key
string | Required

ID of the primary account

Request body application/json

from
string | Required
to
string | Required
amount
number | Required
reference
string

Responses

200 Balance transfer response
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

Example Request

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

Example Responses

200 401 403 404 422
{
  "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"
}