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.
This section shows how you can create, retrieve and modify subaccounts of a primary account.
This section shows how you execute credit, balance and number transfers, as well as viewing past transactions.
This section shows how you can create, retrieve and modify subaccounts of a primary account.
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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account
Unique subaccount ID.
Name of the subaccount.
Unique primary account ID.
Flag showing if balance is shared with primary account.
Subaccount creation date and time.
Subaccount suspension status.
Balance of the subAccount. Value is null if balance is shared with primary account.
Credit limit of the subAccount. Value is null if balance is shared with primary account.
Unique subaccount ID.
Name of the subaccount.
Unique primary account ID.
Flag showing if balance is shared with primary account.
Subaccount creation date and time.
Subaccount suspension status.
Balance of the subAccount. Value is null if balance is shared with primary account.
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"
}
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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account
API secret of the subaccount.
Unique subaccount ID.
Name of the subaccount.
Unique primary account ID.
Flag showing if balance is shared with primary account.
Subaccount creation date and time.
Subaccount suspension status.
Balance of the subAccount. Value is null if balance is shared with primary account.
Credit limit of the subAccount. Value is null if balance is shared with primary account.
{
"name": "Subaccount department A"
}
{
"name": "Subaccount department A",
"secret": "Password123"
}
{
"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"
}
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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account
ID of the subaccount
Unique subaccount ID.
Name of the subaccount.
Unique primary account ID.
Flag showing if balance is shared with primary account.
Subaccount creation date and time.
Subaccount suspension status.
Balance of the subAccount. Value is null if balance is shared with primary account.
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"
}
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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account
ID of the subaccount
Unique subaccount ID.
Name of the subaccount.
Unique primary account ID.
Flag showing if balance is shared with primary account.
Subaccount creation date and time.
Subaccount suspension status.
Balance of the subAccount. Value is null if balance is shared with primary account.
Credit limit of the subAccount. Value is null if balance is shared with primary account.
{
"suspended": true,
"name": "Subaccount department B"
}
{
"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"
}
This section shows how you execute credit, balance and number transfers, as well as viewing past transactions.
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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account.
Start of the retrieval period.
End of the retrieval period. If absent then all transfers until now is returned.
Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts
Unique credit transfer ID
Credit transfer amount
Account the credit is transferred from
Account the credit is transferred to
Reference for the credit transfer
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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account
Unique credit transfer ID
Credit transfer amount
Account the credit is transferred from
Account the credit is transferred to
Reference for the credit transfer
The date and time when the credit transfer was executed
{
"from": "7c9738e6",
"to": "ad6dc56f",
"amount": "123.45"
}
{
"from": "7c9738e6",
"to": "ad6dc56f",
"amount": "123.45",
"reference": "This gets added to the audit log"
}
{
"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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account.
Start of the retrieval period.
End of the retrieval period. If absent then all transfers until now is returned.
Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts
Unique balance transfer ID
Balance transfer amount
Account the balance is transferred from
Account the balance is transferred to
Reference for the balance transfer
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"
}
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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account
Unique balance transfer ID
Balance transfer amount
Account the balance is transferred from
Account the balance is transferred to
Reference for the balance transfer
The date and time when the balance transfer was executed
{
"from": "7c9738e6",
"to": "ad6dc56f",
"amount": "123.45"
}
{
"from": "7c9738e6",
"to": "ad6dc56f",
"amount": "123.45",
"reference": "This gets added to the audit log"
}
{
"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 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
Key | Description | Example | Default |
---|---|---|---|
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
ID of the primary account.
Number transfered
The two character country code in ISO 3166-1 alpha-2 format
Account the number is transferred from
Account the number is transferred to
{
"from": "7c9738e6",
"to": "ad6dc56f",
"number": "23507703696",
"country": "GB"
}
{
"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"
}
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 |