> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization Shareholders API

> Manage beneficial owners and 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 theme={null}
  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 theme={null}
  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 theme={null}
  {
    "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 theme={null}
  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 theme={null}
  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 theme={null}
  {
    "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 theme={null}
  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 theme={null}
  {
    "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 theme={null}
// 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 theme={null}
{
  "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>