An entity on zerohash isn't just the business itself — it also includes the users associated with it: the controlling persons and beneficial owners (CP/BO) that zerohash must identify and verify as part of KYC/KYB. These endpoints let you read and update those users over the life of the entity.
You'll typically manage entity users when:
- Details change — a controlling person or beneficial owner updates their name, address, contact information, or identifiers.
- Ownership or control changes — someone joins or leaves the entity, or ownership is revised, and the entity's records need to reflect the current structure.
- Verification needs updating — a user needs to resubmit or correct information to pass or maintain KYC.
- You need visibility — you want to read a user's profile, screening result, or full KYC record to power internal tooling or compliance workflows.
Keeping entity users accurate matters: zerohash's KYC/KYB checks run against these records, so stale or incomplete user information can hold up verification or affect the entity's standing.
For a full walkthrough of how entity users work, see the Entity user management guide.
Board members
EU entities must submit at least one board member on creation, via the board_members array on Create Entity. Board members are persisted as user records (flagged is_board_member: true) and are a distinct role from control persons and beneficial owners — a board member never substitutes for a required beneficial owner.
Board members:
- Are added only at entity creation.
board_membersis accepted onPOST /participants/entity/newand is not accepted on the entity partial-update endpoint (PATCH /participants/entity/{participant_code}) — that endpoint's schema states board members cannot be added or changed there. - Are read and edited like any other entity user. Once created, a board member is an entity user record keyed by
user_code, retrieved and updated the same way as control persons and beneficial owners — e.g. update an individual board member viaPATCH /participants/entity/{participant_code}/users/{user_code}.
Reading entity user data
Each user is identified within an entity, so these lookups return data for the entity's controlling persons and beneficial owners.
- Get basic info (controlling persons & beneficial owners) — Returns core identifying details for an entity's controlling persons and beneficial owners.
The two endpoints below return sensitive KYC/PII and screening data. They require enablement by the zerohash support team and are subject to a security review prior to enablement.
- Get sanctions screening info (controlling persons & beneficial owners) — Returns the sanctions/watchlist screening results for an entity's controlling persons and beneficial owners.
- Get full info (controlling persons & beneficial owners) — Returns the complete KYC/PII records for an entity's controlling persons and beneficial owners.
Updating entity users
- Update an entity user — Updates the details of a specific user (controlling person or beneficial owner) associated with an entity, identified by the entity's participant code and the user's user code.