Sub-Accounts

A sub-account lets businesses or financial institutions manage multiple entities or clients under a single Verto Parent Account. This feature is designed for partners offering embedded financial experiences or managing multiple client portfolios , giving you full visibility and control across all connected accounts.

How It Works

Sub-accounts allow parent entities to offer a Verto-like experience to their users.
Parent entities can create sub-accounts for their users, giving access to wallets and local accounts.
These sub-accounts operate under the main Parent Account, allowing partners to extend services while maintaining oversight.

Sub-Accounts Structure

Parent Account
│
├── Sub-Account
│   ├── NGN Wallet
│   │   └── Local Account
│   ├── KES Wallet
│   │   └── Local Account
│
└── Sub-Account
    ├── KES Wallet
    │   └── Local Account
    ├── NGN Wallet
        └── Local Account

How to Create Sub-Accounts

There are two ways to create sub-accounts on Verto:

Through the Dashboard
1. Log in to your Parent Account.
2. Navigate to Linked Accounts→ Add Sub-Account.
3. Fill in the required business details for the new sub-account:Legal name,Business Category, Registration Number, External ID
4. Click "update" and you will be redicted to a new page to fill in kyc information and your sub-account will be added with the status as "KYC PENDING"
5. Upload supporting documents such as Certificate of Incorporation, UBO IDs, and Proof of Address.
Through the API

Developers can programmatically create sub-accounts using the endpoint below:

For the complete API specification and test console, visit this link

Endpoint

POST https://api-company-sandbox.vertfx.com/sub-accounts

This endpoint allows partners to create sub-accounts directly via API. Each sub-account represents an entity (client or subsidiary) operating under the parent company’s compliance framework.

Headers

Key	Value	Description
`Authorization`	`Bearer <token>`	JWT access token for authentication.
`Content-Type`	`application/json`	Required.
`Accept`	`application/json`	Required.

Required Body Parameters

Field	Type	Required	Description
`name`	string	✅	Legal name of the company (as registered).
`country`	string	✅	Country where the sub-account is registered (ISO Alpha-2 format).
`subCategory`	string	✅	Company’s industry classification.
`identificationNumber`	string	✅	Registration or incorporation number issued by the local authority.
`taxIdOrEin`	string	❌	Tax identification number or equivalent (if applicable).
`externalId`	string	❌	The company reference ID in your system (for internal mapping).
`accountType`	string	✅	Defines the sub-account’s relationship type (`SUB_CLIENT` or `PARTNER_REFERRED`).

[!IMPORTANT] Validate subCategory before sending the request subCategory must exactly match one of Verto's supported industry classifications. If the submitted value does not match, the API can return an invalid-input error.

Use this list when building your payload: Supported industries

Supported Account Types

Value	Description
`PARTNER_REFERRED`	Used when the end-client has a direct financial relationship with Verto.

Example Request

{
  "name": "string",
  "country": "United Kingdom",
  "subCategory": "Agriculture and farming",
  "identificationNumber": "string",
  "taxIdOrEin": "string",
  "externalId": "string",
  "accountType": "PARTNER_REFERRED"
}

Example Response 201

{
  "id": "string",
  "externalId": "string",
  "parentCompanyId": "string",
  "name": "string",
  "country": null,
  "category": "string",
  "subCategory": "string",
  "identificationNumber": "string",
  "taxIdOrEin": "string",
  "accountType": "PARTNER_REFERRED",
  "companyReference": "string",
  "companyStatus": "CREATED",
  "linkedStatus": "PENDING",
  "linkedAt": "2025-11-12T15:58:37.175Z",
  "createdAt": "2025-11-12T15:58:37.175Z",
  "updatedAt": "2025-11-12T15:58:37.175Z"
}

Response Codes

Code	Meaning	Description
`201 Created`	✅	Sub-account successfully created.
`400 Bad Request`	❌	Missing or invalid fields in the request.
`401 Unauthorized`	❌	Invalid or expired token.
`403 Forbidden`	❌	Insufficient permissions.
`404 Not Found`	❌	Parent account not found.
`500 Internal Server Error`	❌	Unexpected system error

If you receive a 400 Bad Request for an invalid company sub-category, check that your submitted subCategory matches the supported industries list exactly, including spacing and capitalization.

After you've successfully created the sub-account, the your new sub-account will be pending KYC approval and then you can proceed to onboarding.