Create a Sub-Account

Create a sub-account to establish the customer context that will own wallets, compliance records, receive accounts, and payout activity in your Atlas platform integration.

🛠️

Developer Context

Creating a sub-account only requires basic entity metadata. Once created, the account enters a PENDING state until compliance verification is completed.

✅ Before you create the sub-account

Complete these steps first:

1. Authenticate with your master platform credentials.
2. Confirm you are building an Atlas platform flow, not a direct own-funds flow.
3. Gather the legal entity name, jurisdiction, industry category, and registry or identification number for the customer.
4. Decide where you will store the returned sub-account ID because you will need it for all later scoped operations.
5. Validate subCategory against the Supported Industry Classifications page before you send the request.

🚀 API Implementation

Provision a new sub-account by providing the business identity and jurisdiction.

curl -X POST https://api.sandbox.vertofx.com/v2/sub-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Logistical LLC",
    "country": "United Kingdom",
    "subCategory": "Advertising & marketing company",
    "identificationNumber": "UK12345678",
    "accountType": "sub_client"
  }'

subCategory must exactly match one of the supported values on the Supported Industry Classifications page.

When this request succeeds, store the returned sub-account ID and treat it as the parent key for wallets, accounts, statements, beneficiaries, and payouts that belong to that customer.

📋 Required Schema

To ensure a smooth transition to verified status, validate the following fields before submission:

Validate these fields before submission so the customer can move through compliance review without avoidable delays.

🏛️ Contextual Awareness

💡

The "Identity" Header Upon successful creation, the API returns a sub_acc_id (e.g., sub_acc_778899). Save this ID. You will need it in the X-Sub-Account-Id header for every subsequent wallet or payout operation performed for this user.

What happens next

After creation, the sub-account is not ready to transact immediately:

1. Submit the required KYB or KYC data for review.
2. Wait until the sub-account reaches an operationally approved state.
3. Create wallets only after the customer can transact.
4. Issue accounts, receive funds, or send payouts from that sub-account context as needed.

Troubleshooting

🎯 Next Steps