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 or prong
• archive - Archive (remove) an existing beneficial owner

Add Action Requirements:

• userId - The ID of an existing individual (non-anonymous) user in the same company
• ownershipPercent - Ownership percentage (0-100)
• prong - The prong for beneficial ownership (ownership or control)
• 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
• prong (optional) - New prong value

Archive Action Requirements:

• userId - The ID of the beneficial owner to archive

Things to Note:

• Beneficial owners must be existing individual (non-anonymous) users in the same company
• 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