Shareholders & UBOs

Add and manage Ultimate Beneficial Owners (UBOs) and shareholders with >25% ownership or control.

Add Shareholder

`POST /v1/customers/business/:id/shareholders`

Request Example

POST https://platform.swipelux.com/v1/customers/business/cus_xxx/shareholders
Content-Type: application/json
X-API-Key: your_api_key
 
{
  "firstName": "John",
  "lastName": "Doe",
  "birthDate": "1985-06-15",
  "email": "john.doe@acme-invest.example.com",
  "phone": "+15551234567",
  "title": "Managing Director",
  "ownershipPercentage": 51,
  "hasControl": true,
  "isSigner": true,
  "isDirector": true,
  "address": {
    "country": "DE",
    "streetAddress": "123 Main St",
    "city": "Berlin",
    "zip": "10115"
  },
  "identityDocument": {
    "type": "passport",
    "issuingCountry": "DE",
    "number": "C01X00T47"
  }
}

Request Fields

Field	Type	Required	Description
`firstName`	string	Yes	First name
`lastName`	string	Yes	Last name
`birthDate`	string	Yes	Date of birth (YYYY-MM-DD)
`email`	string	Yes	Email address
`phone`	string	No	Phone number
`title`	string	No	Position/title in company
`ownershipPercentage`	number	Yes	Ownership percentage (0-100)
`hasControl`	boolean	Yes	Has control over company decisions
`isSigner`	boolean	Yes	Authorized signer for company
`isDirector`	boolean	Yes	Is a director/board member
`address`	object	Yes	Residential address
`address.country`	string	Yes	Country (ISO 3166-1 alpha-2)
`address.streetAddress`	string	Yes	Street address
`address.city`	string	Yes	City
`address.zip`	string	Yes	Postal/ZIP code
`identityDocument`	object	No	Government-issued ID details
`identityDocument.type`	string	Yes*	ID type (passport, id_card, drivers_license)
`identityDocument.issuingCountry`	string	Yes*	Issuing country (ISO 3166-1 alpha-2)
`identityDocument.number`	string	No	ID number

Document uploads (scans, photos) should be done separately via POST /v1/customers/business/:id/shareholders/:shareholderId/documents after the shareholder is created.

Update Shareholder

`PUT /v1/customers/business/:id/shareholders/:shareholderId`

Request Example

PUT https://platform.swipelux.com/v1/customers/business/cus_xxx/shareholders/bizsh_xxx
Content-Type: application/json
X-API-Key: your_api_key
 
{
  "ownershipPercentage": 60,
  "title": "CEO"
}

All fields from the create request are optional in updates. Only provided fields will be updated.

Delete Shareholder

`DELETE /v1/customers/business/:id/shareholders/:shareholderId`

Request Example

DELETE https://platform.swipelux.com/v1/customers/business/cus_xxx/shareholders/bizsh_xxx
X-API-Key: your_api_key

Upload Shareholder Documents

`POST /v1/customers/business/:id/shareholders/:shareholderId/documents`

POST https://platform.swipelux.com/v1/customers/business/cus_xxx/shareholders/bizsh_xxx/documents
Content-Type: application/json
X-API-Key: your_api_key
 
{
  "type": "proof_of_address",
  "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Supported document types:

passport_front, passport_back
id_card_front, id_card_back
drivers_license_front, drivers_license_back
proof_of_address

UBO Requirements

You must declare all individuals who meet any of these criteria:

Own >25% of the company shares
Control >25% of voting rights
Exercise significant control over management decisions
Are authorized signers on company accounts
Are ultimate beneficial owners through indirect ownership

Common Positions

Typical UBO positions requiring declaration:

CEO, Managing Director, President
CFO, Treasurer
Majority Shareholders
Board Members with control
Trust Beneficiaries (if applicable)

Multiple Shareholders

For companies with multiple UBOs, add each separately:

// Add majority shareholder
await fetch(`/v1/customers/business/${businessId}/shareholders`, {
  method: 'POST',
  headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    firstName: 'Anna',
    lastName: 'Schmidt',
    birthDate: '1980-03-20',
    email: 'anna@company.com',
    ownershipPercentage: 60,
    hasControl: true,
    isSigner: true,
    isDirector: true,
    address: { country: 'DE', streetAddress: '...', city: 'Berlin', zip: '10115' }
  })
});
 
// Add minority shareholder with control
await fetch(`/v1/customers/business/${businessId}/shareholders`, {
  method: 'POST',
  headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    firstName: 'Peter',
    lastName: 'Mueller',
    birthDate: '1975-08-10',
    email: 'peter@company.com',
    ownershipPercentage: 40,
    hasControl: true,
    isSigner: false,
    isDirector: false,
    address: { country: 'DE', streetAddress: '...', city: 'Munich', zip: '80331' }
  })
});

Add Shareholder

`POST /v1/customers/business/:id/shareholders`

Request Example

Request Fields

Update Shareholder

`PUT /v1/customers/business/:id/shareholders/:shareholderId`

Request Example

Delete Shareholder

`DELETE /v1/customers/business/:id/shareholders/:shareholderId`

Request Example

Upload Shareholder Documents

`POST /v1/customers/business/:id/shareholders/:shareholderId/documents`

UBO Requirements

Common Positions

Multiple Shareholders

Next Steps

On this page