Shareholders & UBOs

API Reference

Shareholders are not separate customer entities. They are nested data within the business customer record and are managed via the business customer endpoints.

Managing Shareholders

Shareholders are managed via dedicated CRUD endpoints after creating the business customer:

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

The following fields are available for each shareholder:

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)

Documents (scans, photos) should be uploaded separately via POST /v1/customers/business/{id}/shareholders/{shareholderId}/documents 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
AND they do not have significant control (hasControl: false)
AND 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/customers/business/{id}/shareholders/{shareholderId}/documents

Request Body:

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

Shareholders & UBOs

API Reference

On this page