Customer Accounts (MTA)

Customer Accounts, also called Multi-Tenant Accounts (MTA), let a platform open and manage individual accounts on behalf of its own end customers, all under the platform's relationship with zerohash. Each customer account is identified by a ZRN (zerohash Resource Name) and can be funded, traded, locked, and closed independently.

Use these endpoints to open an account for a participant, keep their account details current, control their access (locks and withdrawal locks), manage who can act on the account (tenants and advisors), and wind the account down when the relationship ends.

All endpoints use standard zerohash API-key authentication (a signed Signature and Timestamp).

Lifecycle at a glance

1. Create a customer account for your end customer.
2. Update its details as the customer's information changes.
3. Control access — lock/unlock the account, or lock/unlock withdrawals specifically.
4. Manage participants — add or remove tenants and advisors associated with the account.
5. Wind down — divest or close the account when it's no longer needed.

Account creation is asynchronous. POST /accounts returns 202 Accepted and finishes provisioning in the background. Listen for the customer_account_status_changed webhook to know when the account is active and ready to use.

What's available

Create & maintain

• Create customer account (POST /accounts) — Open a new customer account. Returns 202; completion is signaled via webhook.
• Update customer account (PATCH /accounts/{zrn}) — Update an existing customer account's details.
• Get account details (GET /accounts/{zrn}/details) — Retrieve the full detail record for a customer account.
• Get customer account status reason (GET /account/{zrn}/status_reason) — Retrieve detailed status information, including lock reason codes. Disabled by default; enabled per platform via feature flag.

Access controls

• Lock account (POST /accounts/{zrn}/lock) — Lock a customer account.
• Unlock account (POST /accounts/{zrn}/unlock) — Remove an account lock.
• Lock withdrawals (POST /accounts/{zrn}/withdraw_lock) — Block withdrawals while keeping the account otherwise usable.
• Unlock withdrawals (POST /accounts/{zrn}/withdraw_unlock) — Re-enable withdrawals.

Participants

• Add tenant (POST /accounts/{zrn}/tenants) — Associate a tenant with the account.
• Remove tenant (DELETE /accounts/{zrn}/tenants/{tenant}) — Remove a tenant from the account.
• Add advisor (POST /accounts/{zrn}/advisors) — Associate a financial advisor with the account.
• Remove advisor (DELETE /accounts/{zrn}/advisors/{financial_advisor}) — Remove an advisor from the account.

Wind-down

• Divest customer account (POST /accounts/{zrn}/divest) — Divest an existing customer account.
• Close customer account (POST /accounts/{zrn}/close) — Close an existing customer account.

Good to know

• ZRN identifier — Customer-account operations are keyed by the account's zrn.
• Asynchronous creation — Always confirm activation via the customer_account_status_changed webhook rather than assuming the account is live on the 202 response.
• Locks vs. withdrawal locks — A full lock restricts account activity; a withdrawal lock blocks only withdrawals, leaving the rest of the account usable.