Skip to navigation
Subaccount Management Transfers Errors
 
 

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.

Download OAS 3 Definition
Improve this specification

Jump to:

Subaccount Management »

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

Transfers »

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

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 | Default: true

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/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
name
string

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,
  "name": "Subaccount department B"
}

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/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, balance and number 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/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/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"
}

Transfer number

Transfer number from one account to another.

POST https://api.nexmo.com/accounts/:api_key/transfer-number
Host https://api.nexmo.com
POST /accounts/:api_key/transfer-number

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
to
string
number
number
country
string

Responses

200 Number transfer response
number
string

Number transfered

country
string

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

from
string

Account the number is transferred from

to
string

Account the number is transferred to

Example Request

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

Example Responses

200 401 403 404 409 422 
{
  "number": "235077036",
  "country": "GB",
  "from": "7c9738e6",
  "to": "ad6dc56f"
}
{
  "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/subaccounts#invalid-number-transfer",
  "title": "Invalid Number Transfer",
  "detail": "Failed to perform transfer number {number} from account {from} to {to} - The relationship between these two accounts does not allow for number transfer",
  "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/subaccounts#missing-number-transfer",
  "title": "Invalid Number Transfer",
  "detail": "Could not transfer number {number} from account {from} to {to} - ShortCode not found",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/subaccounts#transfer-conflict",
  "title": "Transfer Conflict",
  "detail": "Could not transfer number {number} from account {from} to {to} - ShortCode is already owned by requesting account",
  "instance": "158b8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/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"
}

Errors

The following is a non-exhaustive list of error codes that may occur while using this API. These codes are in addition to any of our generic error codes.

Code Details
validation

The request failed due to validation errors
valid-transfers

Invalid transfer
provisioning

Maximum number of sub-accounts reached
internal-error

An error has occurred in the platform while processing this request