Customer Account Types
zerohash offers individual and joint accounts. This guide provides a comprehensive overview of the account types and tenant type definitions, and example flows.
Account Identifiers
In order to facilitate the changes necessary to disambiguate the existing account identifiers from the concept of a customer centric account, zerohash will introduce a formal ZRN (zerohash URN) schema for the identifiers. The decision to use ZRN was driven by the need to provide no impact to existing integrations while providing an explicit method for platforms to specify the type of account being referenced via API. The format for the zrn value is; zrn:zh:<geo>:<domain>:<subdomain>:id returned from the POST /accounts endpoint.
Where
- geo: global entity to which the identifier belongs [us|eu|uk|ww|bz|au]
- domain: the resource to which the identifier belongs [accounts]
- subdomain: the type of the identifier [customer | ledger]
- id: account identifier
sample zrn value;zrn:zh:us:accounts:customer:c820ca4f-24ca-5be6-a502-649ec59e584e
The system will interpret an unqualified identifier as a zrn:zh:us:accounts:id to provide backwards compatibility for existing integrations.
Additionally endpoints requiring the identifier as part of the URL can accept the subdomain:id portion of the fully qualified ZRN for convenience. The platform will assume by interacting with the accounts domain endpoints that the provided IDs will belong to the accounts domain in the geo the api is being served.
The accounts returned by GET /accounts which contain balance information are always ledger accounts.
Account Types
zerohash supports various account types, each with specific tenant configurations and authorization models. The type is set at creation and cannot be changed afterwards. To move a customer to a different structure, create a new account:
| Account Types | Definition |
|---|---|
| Individual | Account owned and controlled by one individual, who has full access to the account and its funds. |
| Business | Account held by a legal entity, managed by the natural persons authorized to act for that entity |
| Uniform Transfers to Minors Act (UTMA) | Custodial accounts for minors, managed by a custodian until the minor reaches the age of majority |
| Trust | Managed by a trustee for the benefit of beneficiaries |
| Joint Tenants in Common (JTIC) | Multiple individuals with potentially unequal ownership; upon death, the deceased's share passes to their estate |
| Joint Tenants with Right of Survivorship (JTWROS) | Equal ownership among individuals; upon death, the deceased's share automatically transfers to surviving tenants |
Each account type has predefined tenant roles and authorization levels, ensuring compliance and proper access control.
Who Can Hold Each Account Type
The account type is a separate choice from the participant type. Business and Trust accounts are held by an entity, so the account holder must be onboarded as a non-natural person before the account can be created.
| Account type | Onboard the primary holder as | Endpoint |
|---|---|---|
| Individual, JTIC, JTWROS, UTMA | Natural person | POST /participants/customers/new |
| Business | Non-natural person (entity) | POST /participants/entity/new |
| Trust | Non-natural person, Trust Entity | POST /participants/entity/new |
Account Creation Fields
| Field | Notes |
|---|---|
participant_code | The primary account holder. Required. |
account_label | Your identifier for the account. Unique per participant, and the idempotency key for POST /accounts. Up to 40 characters from a-z A-Z 0-9 - _ :, no spaces, and cannot start or end with -, _ or :. |
type | The account type. Immutable after creation. |
tier | Commission tier: lite, pro, bronze, silver, gold. |
prefunded | true if the participant funds the account, false if your platform float does. |
tenants | Participant codes of the secondary participants. Required for every type except Individual. |
financial_advisors | Participant codes of advisors. Optional on every account type. |
After creation, only tier and prefunded can be changed, via PATCH /accounts/{zrn}.
Account Creation Is Asynchronous
POST /accountsreturns202 Accepted. The account is not usable until you receive thecustomer_account_status_changedwebhook. Store thezrnfrom the response and wait for the webhook before funding or trading.
Updated 7 days ago