URL: /baas/api/reference/customer-apis/organization/shareholders

---
title: 'Organization Shareholders API'
description: 'Manage beneficial owners and shareholders'
api: 'POST https://sandbox.finhub.cloud/api/v2.1/customer/organization/{organizationId}/shareholders'
---

# Organization Shareholders API

APIs for managing beneficial owners and shareholders of business organizations.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud`
</Info>

## Available Operations

<CardGroup cols={3}>
  <Card title="Add Shareholders" icon="user-plus">
    `POST /v2.1/.../shareholders`
  </Card>
  <Card title="List Shareholders" icon="users">
    `GET /v2/organizations/{id}/shareholders`
  </Card>
  <Card title="Remove Shareholder" icon="user-minus">
    `DELETE /v2/organizations/{id}/shareholders/{shareholderId}`
  </Card>
</CardGroup>

<Warning>
  **Note:** List and Remove operations use the `/api/v2/` endpoint path, while Add uses `/api/v2.1/`.
</Warning>

---

## Add Shareholders (v2.1)

<Note>Adds one or more shareholders to the specified organization.</Note>

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../../schemas/standard-headers) reference documentation.
</Note>

### Before You Start

**Prerequisites:**
- Organization must be registered
- You must have ADMIN_USER role
- Total ownership across all shareholders must equal 100%

**Important Validation Rules:**
- Individual vs Corporate shareholders have different required fields
- Beneficial owners (≥25% ownership) require enhanced due diligence
- Ownership percentages must sum to exactly 100%

### Endpoint

`POST /api/v2.1/customer/organization/{organizationId}/shareholders`

### Request

<ParamField path="organizationId" type="string" required>
  Organization identifier
</ParamField>

<ParamField body="type" type="string" required>
  Shareholder type: `INDIVIDUAL` or `CORPORATE`
</ParamField>

<ParamField body="ownershipPercentage" type="number" required>
  Ownership percentage (0-100)
</ParamField>

<ParamField body="firstName" type="string">
  First name (required for INDIVIDUAL)
</ParamField>

<ParamField body="lastName" type="string">
  Last name (required for INDIVIDUAL)
</ParamField>

<ParamField body="companyName" type="string">
  Company name (required for CORPORATE)
</ParamField>

<ParamField body="isBeneficialOwner" type="boolean">
  Whether this is a beneficial owner (25%+ ownership)
</ParamField>

<ParamField body="isPEP" type="boolean">
  Politically Exposed Person status
</ParamField>

### Code Examples

<CodeGroup>
```bash cURL
curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/shareholders" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "type": "INDIVIDUAL",
    "firstName": "Sarah",
    "lastName": "Investor",
    "dateOfBirth": "1980-05-10",
    "nationality": "FR",
    "ownershipPercentage": 25.0,
    "isBeneficialOwner": true,
    "isPEP": false,
    "address": {
      "street": "789 Investor Blvd",
      "city": "Paris",
      "postalCode": "75001",
      "country": "FR"
    }
  }'
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/shareholders',
  {
    method: 'POST',
    headers: {
      'Accept': 'application/json, text/plain, */*',
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Forwarded-From': 'e2e-test',
      'platform': 'web',
      'deviceId': '356938035643809'
    },
    body: JSON.stringify({
      type: 'INDIVIDUAL',
      firstName: 'Sarah',
      lastName: 'Investor',
      nationality: 'FR',
      ownershipPercentage: 25.0,
      isBeneficialOwner: true,
      isPEP: false
    })
  }
);

const { data } = await response.json();
console.log('Shareholder ID:', data.shareholderId);
```
</CodeGroup>

<ResponseExample>
```json 201 - Success
{
  "success": true,
  "data": {
    "shareholderId": "sh_11111",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```
</ResponseExample>

---

## List Shareholders (v2)

<Note>Retrieves all shareholders for an organization with ownership percentages.</Note>

### Endpoint

`GET /api/v2/organizations/{organizationId}/shareholders`

### Code Examples

<CodeGroup>
```bash cURL
curl -X GET "https://sandbox.finhub.cloud/api/v2/organizations/org_12345/shareholders" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Organization-ID: org_12345" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```

```javascript JavaScript
const response = await fetch(
  'https://sandbox.finhub.cloud/api/v2/organizations/org_12345/shareholders',
  {
    headers: {
      'Accept': 'application/json, text/plain, */*',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-ID': '97e7ff29-15f3-49ef-9681-3bbfcce4f6cd',
      'X-Organization-ID': 'org_12345',
      'X-Forwarded-From': 'e2e-test',
      'platform': 'web',
      'deviceId': '356938035643809'
    }
  }
);

const { data } = await response.json();
data.shareholders.forEach(s => {
  const name = s.type === 'INDIVIDUAL' ? `${s.firstName} ${s.lastName}` : s.companyName;
  console.log(`${name}: ${s.ownershipPercentage}%`);
});
```
</CodeGroup>

<ResponseExample>
```json 200 - Success
{
  "success": true,
  "data": {
    "shareholders": [
      {
        "shareholderId": "sh_12345",
        "type": "INDIVIDUAL",
        "firstName": "Max",
        "lastName": "Owner",
        "ownershipPercentage": 51.0,
        "isBeneficialOwner": true,
        "status": "VERIFIED"
      }
    ]
  }
}
```
</ResponseExample>

---

## Remove Shareholder (v2)

<Note>Removes a shareholder from the organization (requires ADMIN_USER role).</Note>

### Endpoint

`DELETE /api/v2/organizations/{organizationId}/shareholders/{shareholderId}`

### Code Examples

<CodeGroup>
```bash cURL
curl -X DELETE "https://sandbox.finhub.cloud/api/v2/organizations/org_12345/shareholders/sh_12345" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Organization-ID: org_12345" \
  -H "X-User-Roles: ADMIN_USER" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"
```
</CodeGroup>

<ResponseExample>
```json 204 - Success
{
  "success": true
}
```
</ResponseExample>

---

## Beneficial Ownership Rules

- Individuals owning **25% or more** must be declared as beneficial owners
- Corporate shareholders must disclose their own beneficial owners
- PEP (Politically Exposed Person) status must be declared

---

## Shareholder Types Comparison

| Field | Individual Shareholder | Corporate Shareholder |
|-------|----------------------|----------------------|
| **Required** | firstName, lastName, dateOfBirth, nationality | companyName, registrationNumber, country |
| **Ownership** | ownershipPercentage, numberOfShares | ownershipPercentage, numberOfShares |
| **Identity** | Passport/ID number | Tax ID, incorporation docs |
| **Contact** | Personal email, phone | Contact person details |
| **Due Diligence** | PEP check if ≥25% | UBO disclosure required |

---

## Ownership Validation (100% Rule)

When adding shareholders, the system validates that total ownership equals 100%:

```javascript
// Example: Adding multiple shareholders
const shareholders = [
  { name: "Founder A", ownershipPercentage: 60.0 },
  { name: "Founder B", ownershipPercentage: 30.0 },
  { name: "Investor C", ownershipPercentage: 10.0 }
];
// Total: 100% ✅ Valid

// This would fail:
const invalidShareholders = [
  { name: "Founder A", ownershipPercentage: 60.0 },
  { name: "Founder B", ownershipPercentage: 30.0 }
];
// Total: 90% ❌ Invalid - missing 10%
```

---

## Share Classes

| Share Class | Description | Voting Rights |
|------------|-------------|---------------|
| **ORDINARY** | Standard common shares | Yes |
| **PREFERENCE** | Preference shares with priority dividends | Usually limited |
| **REDEEMABLE** | Can be bought back by company | Yes or No |

---

## Response Codes

| Code | Description |
|------|-------------|
| `200` | Shareholders retrieved/updated successfully |
| `201` | Shareholder added successfully |
| `204` | Shareholder removed successfully |
| `400` | Invalid request data or ownership validation failed |
| `409` | Ownership total does not equal 100% |
| `404` | Organization or shareholder not found |
| `500` | Internal server error |

---

## Common Validation Errors

### Error: Ownership Total Mismatch
**Problem:** Total ownership across all shareholders ≠ 100%

**Solution:**
```json
{
  "error": "Ownership validation failed",
  "currentTotal": 95.0,
  "required": 100.0,
  "missing": 5.0
}
```
Review all shareholder percentages and ensure they sum to exactly 100%.

### Error: Beneficial Owner Not Declared
**Problem:** Shareholder with ≥25% ownership not marked as beneficial owner

**Solution:**
Set `isBeneficialOwner: true` for any shareholder with 25% or more ownership.

### Error: Missing Required Fields
**Problem:** Individual shareholder missing personal details

**Solution:**
Ensure all required fields are provided:
- Individual: firstName, lastName, dateOfBirth, nationality
- Corporate: companyName, registrationNumber, taxId, country

---

## API Schema Reference

For the complete OpenAPI schema specification, see the [API Schema Mapping](../../../../doc/mint/API_SCHEMA_MAPPING#add-organization-shareholders) document.

---

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../../schemas/standard-headers">
    Complete HTTP headers reference
  </Card>
  
  <Card title="Organization Registration" icon="building" href="./registration">
    Register new organizations
  </Card>
  
  <Card title="Directors" icon="user-tie" href="./directors">
    Manage organization directors
  </Card>
  
  <Card title="Employees" icon="users" href="./employees">
    Manage organization employees
  </Card>
</CardGroup>