Nominal accounts
Open a real bank account in a subaccount's own name, and follow its approval and KYB.
Overview
A nominal account gives a subaccount a bank account in its
own name, with its CNPJ, Pix keys and balance. Each subaccount can have one nominal
account, identified by its existing subAccountId.
Open it with POST /api/subaccount/{subAccountId}/account, then send the end-user to
the returned onboardingUrl. Poll GET /api/subaccount/{subAccountId}/account for
status; there is no lifecycle webhook yet.
Lifecycle
status stays PENDING until onboarding and KYB complete. KYB starts automatically.
The account can transact only when status is APPROVED and
stableSubAccountStatus is CONFIRMED. A REJECTED account carries a rejectionReason.
POST /api/subaccount/{subAccountId}/account
curl --request POST \
--url https://api.hodle.com.br/api/subaccount/c852df87-ac61-4259-8242-6451658dfedb/account \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"companyName": "Acme Ltda.",
"taxId": "12345678000199",
"representativeTaxId": "12345678901"
}'| Field | Type | Required | Description |
|---|---|---|---|
companyName | string | Yes | Legal name of the company the account is opened for. Up to 120 chars. |
taxId | string | Yes | The company's CNPJ, digits only. |
representativeTaxId | string | No | CPF of the legal representative who will complete the onboarding. |
{
"success": true,
"data": {
"accountRef": "68c0f1a2b3c4d5e6f7a8b9c0",
"subAccountId": "c852df87-ac61-4259-8242-6451658dfedb",
"companyName": "Acme Ltda.",
"taxId": "12345678000199",
"status": "PENDING",
"stableSubAccountStatus": null,
"accountId": null,
"onboardingUrl": "https://onboarding.example.com/...?embed=true",
"rejectionReason": null,
"createdAt": "2026-09-21T14:03:11.000Z"
}
}GET /api/subaccount/{subAccountId}/account
curl --url "https://api.hodle.com.br/api/subaccount/c852df87-ac61-4259-8242-6451658dfedb/account" \
--header "Authorization: Bearer $API_KEY"{
"success": true,
"data": {
"accounts": [
{
"accountRef": "68c0f1a2b3c4d5e6f7a8b9c0",
"subAccountId": "c852df87-ac61-4259-8242-6451658dfedb",
"companyName": "Acme Ltda.",
"taxId": "12345678000199",
"status": "APPROVED",
"stableSubAccountStatus": "CONFIRMED",
"accountId": "acc_9f2b...",
"onboardingUrl": "https://onboarding.example.com/...?embed=true",
"rejectionReason": null,
"createdAt": "2026-09-21T14:03:11.000Z"
}
]
}
}stableSubAccountStatus is IN_REVIEW or AWAITING_DOCUMENTS while review is pending.
Errors
| Status | When |
|---|---|
400 | Invalid request, or onboarding could not be started. |
401 | Missing or invalid API key. |
404 | Subaccount not found under your platform. |
409 | The subaccount already has a nominal account (ACCOUNT_ALREADY_EXISTS). |