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 OpenAPI Specification

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.

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account

Responses
Content Type
application/json

Subaccounts response

_embedded

object

primary_account

api_key

string

examplebbe6222f

Unique subaccount ID.

name

string

exampleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exampleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exampletrue

Flag showing if balance is shared with primary account.

created_at

string

example2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

example100.25

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

credit_limit

number

example-100.25

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

subaccounts

array

api_key

string

examplebbe6222f

Unique subaccount ID.

name

string

exampleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exampleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exampletrue

Flag showing if balance is shared with primary account.

created_at

string

example2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

example100.25

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

credit_limit

number

example-100.25

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

Example Response

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account

Request Body
Content Type
application/json

name

string

Required

Max80

exampleSubaccount department A

secret

string

examplePassword123

use_primary_account_balance

boolean

Defaulttrue

Example Request

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

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

Responses
Content Type
application/json

Subaccount response

secret

string

examplePassword123

API secret of the subaccount.

api_key

string

examplebbe6222f

Unique subaccount ID.

name

string

exampleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exampleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exampletrue

Flag showing if balance is shared with primary account.

created_at

string

example2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

example100.25

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

credit_limit

number

example-100.25

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

Example Response

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account

subaccount_key

string

Required

ID of the subaccount

Responses
Content Type
application/json

Subaccount response

api_key

string

examplebbe6222f

Unique subaccount ID.

name

string

exampleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exampleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exampletrue

Flag showing if balance is shared with primary account.

created_at

string

example2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

example100.25

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

credit_limit

number

example-100.25

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

Example Response

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account

subaccount_key

string

Required

ID of the subaccount

Request Body
Content Type
application/json

suspended

boolean

exampletrue

use_primary_account_balance

boolean

name

string

exampleSubaccount department B

Example Request

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

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

Responses
Content Type
application/json

Subaccount response

api_key

string

examplebbe6222f

Unique subaccount ID.

name

string

exampleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exampleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exampletrue

Flag showing if balance is shared with primary account.

created_at

string

example2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

example100.25

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

credit_limit

number

example-100.25

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

Example Response

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

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.

gethttps://api.nexmo.com/accounts/:api_key/credit-transfers

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account.

Query Parameters

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

Responses
Content Type
application/json

List credit transfers response

_embedded

object

credit-transfers

array

credit_transfer_id

string

example07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

example123.45

Credit transfer amount

from

string

example7c9738e6

Account the credit is transferred from

string

examplead6dc56f

Account the credit is transferred to

reference

string

exampleThis gets added to the audit log

Reference for the credit transfer

created_at

string

example2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Example Response

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account

Request Body
Content Type
application/json

from

string

Required

example7c9738e6

string

Required

examplead6dc56f

amount

number

Required

example123.45

reference

string

exampleThis gets added to the audit log

Example Request

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

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

Responses
Content Type
application/json

Credit transfer response

credit_transfer_id

string

example07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

example123.45

Credit transfer amount

from

string

example7c9738e6

Account the credit is transferred from

string

examplead6dc56f

Account the credit is transferred to

reference

string

exampleThis gets added to the audit log

Reference for the credit transfer

created_at

string

example2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Example Response

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account.

Query Parameters

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

Responses
Content Type
application/json

List balance transfers response

_embedded

object

balance_transfers

array

balance_transfer_id

string

example07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

example123.45

Balance transfer amount

from

string

example7c9738e6

Account the balance is transferred from

string

examplead6dc56f

Account the balance is transferred to

reference

string

exampleThis gets added to the audit log

Reference for the balance transfer

created_at

string

example2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Example Response

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account

Request Body
Content Type
application/json

from

string

Required

example7c9738e6

string

Required

examplead6dc56f

amount

number

Required

example123.45

reference

string

exampleThis gets added to the audit log

Example Request

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

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

Responses
Content Type
application/json

Balance transfer response

balance_transfer_id

string

example07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

example123.45

Balance transfer amount

from

string

example7c9738e6

Account the balance is transferred from

string

examplead6dc56f

Account the balance is transferred to

reference

string

exampleThis gets added to the audit log

Reference for the balance transfer

created_at

string

example2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Example Response

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

Authentication

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

Path Parameters

api_key

string

Required

ID of the primary account.

Request Body
Content Type
application/json

from

string

example7c9738e6

string

examplead6dc56f

number

example23507703696

country

string

exampleGB

Example Request

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

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

Responses
Content Type
application/json

Number transfer response

number

string

example235077036

Number transfered

country

string

exampleGB

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

from

string

example7c9738e6

Account the number is transferred from

string

examplead6dc56f

Account the number is transferred to

Example Response

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

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	Information
validation	Description The request failed due to validation errors Resolution See the `detail` (and, if present, the `invalid_parameters`) fields for the exact reason this request was rejected and review the documentation.
invalid-transfers	Description Invalid transfer Resolution See the `detail` field for the reason this transfer is invalid.
provisioning	Description Maximum number of sub-accounts reached Resolution If you need more subaccounts, contact Vonage Support.
internal-error	Description An error has occurred in the platform while processing this request Resolution If the error persists, contact Vonage Support.
invalid-number-transfer	Description Failed to perform transfer number from source account to destination account Resolution See the `detail` field for the reason this transfer is invalid.
missing-number-transfer	Description Could not transfer number from source account to destination account - ShortCode not found Resolution See the `detail` field for the reason this transfer is invalid.
transfer-conflict	Description Could not transfer number from source account to destination account - ShortCode is already owned by requesting account Resolution See the `detail` field for the reason this transfer is invalid.

Subaccounts API

Subaccount Management

Available Operations

Retrieve list of subaccounts

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Create subaccount

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve a subaccount

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Modify a subaccount

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Transfers

Available Operations

Retrieve list of credit transfers

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Example Response

Transfer credit

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve list of balance transfers

Authentication

Path Parameters

Query Parameters

Responses Content Typeapplication/json

Example Response

Transfer balance

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Transfer number

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Errors

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json