Vonage Subaccounts
Documentation / Vonage Subaccounts
This is the Vonage Sub Accounts SDK for Node.js for use with Vonage APIs. To use it you will need a Vonage account. Sign up for free at vonage.com.
For full API documentation refer to developer.vonage.com.
npm install @vonage/subaccountsyarn add @vonage/subaccountsUnlike the other SDK's this package is not include in the Vonage Server SDK for Node.js
const { Auth } = require('@vonage/auth')
const { SubAccounts } = require('@vonage/subaccounts')
const credentials = new Auth({
applicationId: APP_ID,
privateKey: PRIAVTE_KEY,
})
const options = {}
const subAccountClient = new SubAccounts(credentials, options)Where credentials is any option from @vonage/auth, and options is any option from @vonage/server-client
Most methods that interact with the Vonage API uses Promises. You can either resolve these yourself, or use await to wait for a response.
const resp = await subAccountClient.listSubAccounts()
subAccountClient
.listSubAccounts()
.then((resp) => console.log(resp))
.catch((err) => console.error(err))Run:
npm run testDefined in: subaccounts/lib/subaccount.ts:29
Represents a client for interacting with Vonage Subaccounts API. This class provides methods for managing subaccounts, credit transfers, balance transfers, and number transfers.
new SubAccounts(credentials, options?): SubAccounts;Defined in: server-client/dist/lib/client.d.ts:35
Creates a new instance of the Client.
The authentication credentials or an authentication instance.
Optional configuration settings for the client.
protected auth: AuthInterface;Defined in: server-client/dist/lib/client.d.ts:24
The authentication instance responsible for generating authentication headers and query parameters.
protected authType: AuthenticationType = AuthenticationType.BASIC;Defined in: subaccounts/lib/subaccount.ts:30
The type of authentication used for the client's requests.
protected config: ConfigParams;Defined in: server-client/dist/lib/client.d.ts:28
Configuration settings for the client, including default hosts for various services and other request settings.
static transformers: object;Defined in: server-client/dist/lib/client.d.ts:11
Static property containing utility transformers.
camelCaseObjectKeys: PartialTransformFunction;kebabCaseObjectKeys: PartialTransformFunction;omit: (keys, obj) => TransformedObject;string[]
snakeCaseObjectKeys: PartialTransformFunction;addAuthenticationToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:43
Adds the appropriate authentication headers or parameters to the request based on the authentication type.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addAuthenticationToRequest
protected addBasicAuthToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:71
Adds basic authentication headers to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
protected addJWTToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:64
Adds a JWT to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
protected addQueryKeySecretToRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:57
Adds API key and secret to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequest
protected addQueryKeySecretToRequestBody(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:50
Adds API key and secret to the request body.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequestBody
createSubAccount(subAccount): Promise<SubAccount>;Defined in: subaccounts/lib/subaccount.ts:73
Creates a new subaccount under the primary account.
The parameters for creating the subaccount.
Promise<SubAccount>
A promise that resolves to the created subaccount information.
getConfig(): ConfigParams;Defined in: server-client/dist/lib/client.d.ts:36
getPrimaryAccount(): Promise<Account>;Defined in: subaccounts/lib/subaccount.ts:60
Retrieves information about the primary account associated with the subaccounts.
Promise<Account>
A promise that resolves to information about the primary account.
getSubAccount(subAccountId): Promise<SubAccount>;Defined in: subaccounts/lib/subaccount.ts:90
Retrieves information about a specific subaccount by its ID.
string
The ID of the subaccount to retrieve.
Promise<SubAccount>
A promise that resolves to the subaccount information.
getSubAccountPage(): Promise<SubAccountResponsePage>;Defined in: subaccounts/lib/subaccount.ts:37
Retrieves a page of subaccounts associated with the primary account.
Promise<SubAccountResponsePage>
A promise that resolves to a page of subaccount information.
listBalanceTransfers(params): Promise<BalanceTransfer[]>;Defined in: subaccounts/lib/subaccount.ts:159
Retrieves a list of balance transfers that have taken place for a primary account within a specified time period.
The parameters for filtering balance transfers.
Promise<BalanceTransfer[]>
A promise that resolves to an array of balance transfer information.
listCreditTransfers(params): Promise<CreditTransfer[]>;Defined in: subaccounts/lib/subaccount.ts:123
Retrieves a list of credit transfers that have taken place for a primary account within a specified time period.
The parameters for filtering the list of credit transfers.
Promise<CreditTransfer[]>
A promise that resolves to an array of credit transfer information.
listSubAccounts(): Promise<SubAccount[]>;Defined in: subaccounts/lib/subaccount.ts:50
Retrieves a list of subaccounts associated with the primary account.
Promise<SubAccount[]>
A promise that resolves to an array of subaccount information.
protected parseResponse<T>(request, response): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:168
Parses the response based on its content type.
T
The expected type of the parsed response data.
The request options.
Response
The raw response from the request.
Promise<VetchResponse<T>>
- The parsed response.
protected prepareBody(request): undefined | string;Defined in: server-client/dist/lib/client.d.ts:158
Prepares the body for the request based on the content type.
The request options.
undefined | string
- The prepared request body as a string or undefined.
protected prepareRequest(request): Promise<VetchOptions>;Defined in: server-client/dist/lib/client.d.ts:151
Prepares the request with necessary headers, authentication, and query parameters.
The initial request options.
Promise<VetchOptions>
- The modified request options.
sendDeleteRequest<T>(url): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:78
Sends a DELETE request to the specified URL.
T
string
The URL endpoint for the DELETE request.
Promise<VetchResponse<T>>
- The response from the DELETE request.
sendFormSubmitRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:86
Sends a POST request with form data to the specified URL.
T
string
The URL endpoint for the POST request.
Record<string, undefined | string>
Optional payload containing form data to send with the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
sendGetRequest<T>(url, queryParams?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:94
Sends a GET request to the specified URL with optional query parameters.
T
string
The URL endpoint for the GET request.
Optional query parameters to append to the URL. These should be compatible with Node's URLSearchParams.
Promise<VetchResponse<T>>
- The response from the GET request.
sendPatchRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:104
Sends a PATCH request to the specified URL with an optional payload.
T
string
The URL endpoint for the PATCH request.
Optional payload to be sent as the body of the PATCH request.
Promise<VetchResponse<T>>
- The response from the PATCH request.
sendPostRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:114
Sends a POST request to the specified URL with an optional payload.
T
string
The URL endpoint for the POST request.
Optional payload to be sent as the body of the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
sendPutRequest<T>(url, payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:124
Sends a PUT request to the specified URL with an optional payload.
T
string
The URL endpoint for the PUT request.
Optional payload to be sent as the body of the PUT request.
Promise<VetchResponse<T>>
- The response from the PUT request.
sendRequest<T>(request): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:144
Sends a request adding necessary headers, handling authentication, and parsing the response.
T
The options defining the request, including URL, method, headers, and data.
Promise<VetchResponse<T>>
- The parsed response from the request.
sendRequestWithData<T>(
method,
url,
payload?): Promise<VetchResponse<T>>;Defined in: server-client/dist/lib/client.d.ts:135
Sends a request with JSON-encoded data to the specified URL using the provided HTTP method.
T
The HTTP method to be used for the request (only POST, PATCH, or PUT are acceptable).
string
The URL endpoint for the request.
Optional payload to be sent as the body of the request, JSON-encoded.
Promise<VetchResponse<T>>
- The response from the request.
transferBalance(params): Promise<BalanceTransfer>;Defined in: subaccounts/lib/subaccount.ts:178
Transfers balance between a primary account and one of its subaccounts.
The parameters for the balance transfer.
Promise<BalanceTransfer>
A promise that resolves to the details of the balance transfer.
transferCredit(params): Promise<CreditTransfer>;Defined in: subaccounts/lib/subaccount.ts:142
Transfers credit limit between a primary account and one of its subaccounts.
The parameters for transferring credit.
Promise<CreditTransfer>
A promise that resolves to information about the credit transfer.
transferNumber(params): Promise<NumberTransfer>;Defined in: subaccounts/lib/subaccount.ts:197
Transfers a phone number from one account to another.
The parameters for the number transfer.
Promise<NumberTransfer>
A promise that resolves to the details of the number transfer.
updateSubAccount(subAccountId, params): Promise<SubAccount>;Defined in: subaccounts/lib/subaccount.ts:105
Modifies one or more properties of a specific subaccount.
string
The ID of the subaccount to modify.
The parameters for modifying the subaccount.
Promise<SubAccount>
A promise that resolves to the modified subaccount information.
type Account = object;Defined in: subaccounts/lib/types/account.ts:5
Type definition representing an account, which includes properties such as
apiKey, name, createdAt, suspended, balance, and creditLimit.
apiKey: string;Defined in: subaccounts/lib/types/account.ts:9
The API key associated with the account.
balance: number;Defined in: subaccounts/lib/types/account.ts:29
The balance of the account.
createdAt: string;Defined in: subaccounts/lib/types/account.ts:19
The creation date and time of the account.
creditLimit: number;Defined in: subaccounts/lib/types/account.ts:34
The credit limit of the account.
name: string;Defined in: subaccounts/lib/types/account.ts:14
The name of the account.
suspended: boolean;Defined in: subaccounts/lib/types/account.ts:24
The suspension status of the account.
type AccountResponse = object & Omit<SubAccount,
| "apiKey"
| "primaryAccountApiKey"
| "usePrimaryAccountBalance"
| "createdAt"
| "creditLimit">;Defined in: subaccounts/lib/types/responses/accountResponse.ts:13
Type definition for the response representing an account, which includes
properties such as api_key, created_at, balance, and credit_limit.
This type combines properties from the account response with the properties
of a subaccount (excluding specific subaccount-related properties).
api_key: string;The API key associated with the account.
balance: number;The balance of the account.
created_at: string;The creation date and time of the account.
credit_limit: number;The credit limit of the account.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type BalanceTransfer = object;Defined in: subaccounts/lib/types/balanceTransfer.ts:5
Type definition representing a balance transfer, which includes properties
such as balanceTransferId, amount, from, to, reference, and createdAt.
amount: number;Defined in: subaccounts/lib/types/balanceTransfer.ts:14
The amount of the balance transfer.
balanceTransferId: string;Defined in: subaccounts/lib/types/balanceTransfer.ts:9
The unique identifier for the balance transfer.
createdAt: string;Defined in: subaccounts/lib/types/balanceTransfer.ts:34
The date and time when the balance transfer was executed.
from: string;Defined in: subaccounts/lib/types/balanceTransfer.ts:19
The source account from which the balance is transferred.
reference: string;Defined in: subaccounts/lib/types/balanceTransfer.ts:29
A reference for the balance transfer.
to: string;Defined in: subaccounts/lib/types/balanceTransfer.ts:24
The destination account to which the balance is transferred.
type BalanceTransferListParameters = object;Defined in: subaccounts/lib/types/parameters/balanceTransferListParameters.ts:4
Type definition for parameters used to retrieve a list of balance transfers for a primary account.
optional endDate: string;Defined in: subaccounts/lib/types/parameters/balanceTransferListParameters.ts:13
The end date of the retrieval period. If absent, all transfers until now are returned.
startDate: string;Defined in: subaccounts/lib/types/parameters/balanceTransferListParameters.ts:8
The start date of the retrieval period.
optional subaccount: string;Defined in: subaccounts/lib/types/parameters/balanceTransferListParameters.ts:18
Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts.
type BalanceTransferPageResponse = object & APILinks;Defined in: subaccounts/lib/types/responses/balanceTransferPageResponse.ts:12
Type definition for the response representing a page of balance transfers,
which includes an array of balance_transfers and APILinks.
_embedded: object;An object containing an array of balance_transfers.
_embedded.balance_transfers: BalanceTransferResponse[];Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type BalanceTransferParameters = object;Defined in: subaccounts/lib/types/parameters/balanceTransferParameters.ts:4
Type definition for parameters used to transfer balance between accounts.
amount: number;Defined in: subaccounts/lib/types/parameters/balanceTransferParameters.ts:18
The amount of balance to transfer.
from: string;Defined in: subaccounts/lib/types/parameters/balanceTransferParameters.ts:8
The account ID from which the balance is transferred.
optional reference: string;Defined in: subaccounts/lib/types/parameters/balanceTransferParameters.ts:23
(Optional) A reference for the balance transfer.
to: string;Defined in: subaccounts/lib/types/parameters/balanceTransferParameters.ts:13
The account ID to which the balance is transferred.
type BalanceTransferResponse = object & Omit<BalanceTransfer, "balanceTransferId" | "createdAt">;Defined in: subaccounts/lib/types/responses/balanceTransferResponse.ts:12
Type definition for the response representing a balance transfer, which includes properties such as
balance_transfer_id and created_at. This type combines properties from the balance transfer response with the
properties of a BalanceTransfer (excluding specific properties).
balance_transfer_id: string;The unique identifier for the balance transfer.
created_at: string;The date and time when the balance transfer was executed.
Vonage API's will return information using snake_case. This represents the pure response before the client will
transform the keys into camelCase.
type CreditTransfer = object;Defined in: subaccounts/lib/types/creditTransfer.ts:5
Type definition representing a credit transfer, which includes properties such as creditTransferId, amount,
from, to, reference, and createdAt.
amount: number;Defined in: subaccounts/lib/types/creditTransfer.ts:14
The amount of the credit transfer.
createdAt: string;Defined in: subaccounts/lib/types/creditTransfer.ts:34
The date and time when the credit transfer was executed.
creditTransferId: string;Defined in: subaccounts/lib/types/creditTransfer.ts:9
The unique identifier for the credit transfer.
from: string;Defined in: subaccounts/lib/types/creditTransfer.ts:19
The source account from which the credit is transferred.
reference: string;Defined in: subaccounts/lib/types/creditTransfer.ts:29
A reference for the credit transfer.
to: string;Defined in: subaccounts/lib/types/creditTransfer.ts:24
The destination account to which the credit is transferred.
type CreditTransferListParameters = object;Defined in: subaccounts/lib/types/parameters/creditTransferListParameters.ts:4
Type definition for parameters used to retrieve a list of credit transfers for a primary account.
optional endDate: string;Defined in: subaccounts/lib/types/parameters/creditTransferListParameters.ts:13
(Optional) The end date of the retrieval period. If absent, all transfers until now are returned.
startDate: string;Defined in: subaccounts/lib/types/parameters/creditTransferListParameters.ts:8
The start date of the retrieval period.
optional sub: string;Defined in: subaccounts/lib/types/parameters/creditTransferListParameters.ts:18
(Optional) Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts.
type CreditTransferParameters = object;Defined in: subaccounts/lib/types/parameters/creditTransferParameters.ts:4
Type definition for parameters used to perform a credit transfer between accounts.
amount: string;Defined in: subaccounts/lib/types/parameters/creditTransferParameters.ts:18
The amount of credit to transfer.
from: string;Defined in: subaccounts/lib/types/parameters/creditTransferParameters.ts:8
The account ID from which the credit is transferred.
optional reference: string;Defined in: subaccounts/lib/types/parameters/creditTransferParameters.ts:23
(Optional) A reference for the credit transfer.
to: string;Defined in: subaccounts/lib/types/parameters/creditTransferParameters.ts:13
The account ID to which the credit is transferred.
type CreditTransferResponse = object & Omit<CreditTransfer, "creditTransferId" | "createdAt">;Defined in: subaccounts/lib/types/responses/creditTransferResponse.ts:13
Type definition for the response representing a credit transfer, which
includes properties such as credit_transfer_id and created_at. This type
combines properties from the credit transfer response with the properties of
a CreditTransfer (excluding specific properties).
created_at: string;The date and time when the credit transfer was executed.
credit_transfer_id: string;The unique identifier for the credit transfer.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type CreditTransferResponsePage = object;Defined in: subaccounts/lib/types/responses/creditTransferResponsePage.ts:11
Type definition for the response representing a page of credit transfers,
which includes an array of credit_transfers.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
_embedded: object;Defined in: subaccounts/lib/types/responses/creditTransferResponsePage.ts:15
An object containing an array of credit_transfers.
credit_transfers: CreditTransferResponse[];type NumberTransfer = object;Defined in: subaccounts/lib/types/numberTransfer.ts:5
Type definition representing a number transfer, which includes properties such as number, country, from, and
to.
country: string;Defined in: subaccounts/lib/types/numberTransfer.ts:14
The two-character country code in ISO 3166-1 alpha-2 format.
from: string;Defined in: subaccounts/lib/types/numberTransfer.ts:19
The source account from which the number is transferred.
number: string;Defined in: subaccounts/lib/types/numberTransfer.ts:9
The number being transferred.
to: string;Defined in: subaccounts/lib/types/numberTransfer.ts:24
The destination account to which the number is transferred.
type SubAccount = object & Account;Defined in: subaccounts/lib/types/subAccount.ts:8
Type definition representing a subaccount, which includes properties such
as primaryAccountApiKey and usePrimaryAccountBalance, in addition to
properties from the Account type.
primaryAccountApiKey: string;The API key associated with the primary account.
usePrimaryAccountBalance: boolean;Flag indicating whether to use the primary account balance (true) or not (false).
type SubAccountCreateParameters = object;Defined in: subaccounts/lib/types/parameters/subAccountCreateParameters.ts:4
Type definition for parameters used to create a subaccount for a primary account.
name: string;Defined in: subaccounts/lib/types/parameters/subAccountCreateParameters.ts:8
Name of the subaccount.
optional secret: string;Defined in: subaccounts/lib/types/parameters/subAccountCreateParameters.ts:20
API secret of the subaccount.
- At least 8 characters and no more than 25 characters
- Contains at least 1 lower-case letter
- Contains at least 1 capital letter
- Contains at least 1 digit
- Must be unique
If this parameter is not provided, a secret will be automatically generated and you can check it on the dashboard.
optional usePrimaryAccountBalance: boolean;Defined in: subaccounts/lib/types/parameters/subAccountCreateParameters.ts:26
Flag indicating whether to use the primary account balance (true) or not (false). Default value is true.
type SubAccountCreateRequest = object & Omit<SubAccountCreateParameters, "usePrimaryAccountBalance">;Defined in: subaccounts/lib/types/requests/subAccountCreateRequest.ts:8
Type definition for the request used to create a subaccount for a primary account.
It combines the use_primary_account_balance property with the properties from SubAccountCreateParameters
while omitting the usePrimaryAccountBalance property.
use_primary_account_balance: boolean;Flag indicating whether to use the primary account balance (true) or not (false).
type SubAccountModifyParameters = object;Defined in: subaccounts/lib/types/parameters/subAccountModifyParameters.ts:4
Type definition for parameters used to modify a subaccount's properties.
optional name: string;Defined in: subaccounts/lib/types/parameters/subAccountModifyParameters.ts:13
(Optional) New name for the subaccount.
optional suspended: boolean;Defined in: subaccounts/lib/types/parameters/subAccountModifyParameters.ts:8
(Optional) Indicates whether the subaccount should be suspended (true) or not (false).
type SubAccountResponse = object & AccountResponse;Defined in: subaccounts/lib/types/responses/subAccountResponse.ts:13
Type definition for the response representing a subaccount, which includes
properties such as primary_account_api_key and
use_primary_account_balance. This type combines properties from the
subaccount response with the properties of an AccountResponse.
primary_account_api_key: string;The API key associated with the primary account.
use_primary_account_balance: boolean;Flag indicating whether to use the primary account balance (true) or not (false).
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type SubAccountResponsePage = object & APILinks;Defined in: subaccounts/lib/types/responses/subAccountResponsePage.ts:14
Type definition for the response representing a page of subaccounts, which
includes properties such as total_balance, total_credit_limit,
_embedded with primary_account, subaccounts, and APILinks.
_embedded: object;An object containing the primary account information and an array of subaccounts.
_embedded.primary_account: AccountResponse;_embedded.subaccounts: SubAccountResponse[];total_balance: number;The total balance of the subaccounts.
total_credit_limit: number;The total credit limit of the subaccounts.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type TransferListParameters = object;Defined in: subaccounts/lib/types/parameters/transferListParameters.ts:4
Type definition for parameters used to retrieve a list of transfers for a primary account.
optional endDate: string;Defined in: subaccounts/lib/types/parameters/transferListParameters.ts:13
(Optional) The end date of the retrieval period. If absent, all transfers until now are returned.
startDate: string;Defined in: subaccounts/lib/types/parameters/transferListParameters.ts:8
The start date of the retrieval period.
optional subAccount: string;Defined in: subaccounts/lib/types/parameters/transferListParameters.ts:18
(Optional) Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts.