Use /entity/:id/beneficialOwners (PATCH) to manage beneficial owners for an entity. This endpoint supports adding new beneficial owners, editing existing ones, and archiving beneficial owners.

Actions:

Each item in the beneficialOwners array must specify an action type:

• add - Add a new beneficial owner to the entity
• edit - Update an existing beneficial owner's ownership percentage, role, or CIP requirement
• archive - Archive (remove) an existing beneficial owner

Add Action Requirements:

• userId - The ID of an existing user in the same company (an individual non-anonymous user, or an entity user for business beneficial owners)
• beneficialOwnerType (optional) - individual or business (defaults to individual)
• role (optional) - The beneficial owner's role (e.g. ceo, director, parent_company); must be allowed for the beneficialOwnerType (see the list below)
• ownershipPercent - Ownership percentage (0-100)
• cipRequired - Whether CIP is required for this beneficial owner (defaults to true)

Edit Action Requirements:

• userId - The ID of the beneficial owner to edit
• ownershipPercent (optional) - New ownership percentage
• role (optional) - New role; must be allowed for the beneficial owner's existing beneficialOwnerType
• cipRequired (optional) - New CIP requirement

Archive Action Requirements:

• userId - The ID of the beneficial owner to archive

Things to Note:

• Individual beneficial owners must be existing individual (non-anonymous) users in the same company; business beneficial owners must be existing entity users in the same company
• beneficialOwnerType cannot be changed after a beneficial owner is added
• When a beneficial owner is added, a linkage is created on their user record
• When a beneficial owner is archived, their linkage is updated with an archive date
• Multiple actions can be performed in a single request

Valid role values by beneficialOwnerType:

• individual only: controlling_person, ceo, cfo, coo, president, vice_president, secretary, treasurer, director, managing_member, authorized_signer, sole_proprietor, grantor
• business only: parent_company, holding_company
• Either type: beneficial_owner, shareholder, member, general_partner, limited_partner, trustee, other

A role that is not allowed for the owner's beneficialOwnerType is rejected — controlling_person is the FinCEN CDD Rule control prong (a single individual with significant responsibility to control, manage, or direct the entity), so a business beneficial owner cannot hold it and belongs on the ownership side instead (for example beneficial_owner, parent_company or holding_company).