Shareholders & UBOs

API Reference

Shareholders are not separate customer entities. They are records under the business customer and are managed with the business customer endpoints.

Managing Shareholders

Create the business customer first, then manage shareholders with the dedicated endpoints:

POST   /v1/customers/business/{id}/shareholders              # Create shareholder
GET    /v1/customers/business/{id}/shareholders              # List all shareholders
GET    /v1/customers/business/{id}/shareholders/{shId}       # Get single shareholder
PUT    /v1/customers/business/{id}/shareholders/{shId}       # Update shareholder
DELETE /v1/customers/business/{id}/shareholders/{shId}       # Delete shareholder

Shareholder Fields

Each shareholder record can include the following fields:

Field	Type	Required	Description
`firstName`	string	Yes	First name
`lastName`	string	Yes	Last name
`birthDate`	date	Yes	Date of birth (YYYY-MM-DD)
`email`	string	Yes	Email address
`ownershipPercentage`	number	Yes	Ownership percentage (0-100)
`hasControl`	boolean	Yes	Has significant control over the company
`isSigner`	boolean	Yes	Authorized to sign on behalf of company
`isDirector`	boolean	Yes	Is a director/board member
`address`	object	Yes	Residential address (see Address Object)
`phone`	string	No	Phone number
`title`	string	No	Role/title (CEO, CFO, Director, etc.)
`identityDocument`	object	No	Government ID details (type, issuingCountry, number)
`attestedOwnershipStructureAt`	datetime	No	Timestamp when control person attested to ownership structure (ISO 8601)

Upload shareholder scans and photos separately with POST /v1/documents and the shareholder's shareholderId after the shareholder is created.

Shareholder Address Object

All fields are required:

Field	Type	Description
`streetAddress`	string	Street address
`city`	string	City
`country`	string	Country (ISO 3166-1 alpha-2)
`zip`	string	Postal/ZIP code

Identity Document Object

The identityDocument field captures government-issued ID details:

Field	Type	Required	Description
`type`	string	Yes	ID type (passport, id_card, drivers_license)
`issuingCountry`	string	Yes	Country that issued the ID (ISO 3166-1 alpha-2)
`number`	string	No	ID number

Ultimate Beneficial Owners (UBOs)

Definition

Ultimate Beneficial Owner (UBO): An individual who directly or indirectly owns or controls 25% or more of the business.

Control Person: An individual with significant responsibility to control or direct the business, typically an executive officer (CEO, CFO, COO, President) or Director.

UBO Threshold

Jurisdiction	Ownership Threshold
All supported countries	25%

When Shareholders Can Be Omitted

You can omit a shareholder if:

They own less than 25% of the company
They do not have significant control (hasControl: false)
They are not a director (isDirector: false)

You cannot omit:

Any individual owning 25% or more
Control persons (regardless of ownership %)
Directors with significant influence

If no individual owns 25% or more, you must still identify at least one control person (typically the CEO or managing director) with hasControl: true.

Shareholder Identity Documents

Document Type	Code	Context
Passport (front)	`passport_front`	`shareholder`
Passport (back)	`passport_back`	`shareholder`
ID Card (front)	`id_card_front`	`shareholder`
ID Card (back)	`id_card_back`	`shareholder`
Driver's License (front)	`drivers_license_front`	`shareholder`
Driver's License (back)	`drivers_license_back`	`shareholder`
Proof of Address	`proof_of_address`	`shareholder`

Upload Shareholder Document

POST /v1/documents

Request Body:

{
  "shareholderId": "bizsh_xxxxxxxxxxxxxxxxxx",
  "type": "passport_front",
  "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Shareholders & UBOs

API Reference

On this page