FinHub
Open Developer Portal

Organization Shareholders API

Manage beneficial owners and shareholders

Organization Shareholders API

APIs for managing beneficial owners and shareholders of business organizations.

Available Operations

Add Shareholders

POST /v2.1/.../shareholders

List Shareholders

GET /v2/organizations/{id}/shareholders

Remove Shareholder

DELETE /v2/organizations/{id}/shareholders/{shareholderId}

Add Shareholders (v2.1)

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

organizationId string path required

Organization identifier

type string body required

Shareholder type: INDIVIDUAL or CORPORATE

ownershipPercentage number body required

Ownership percentage (0-100)

firstName string body

First name (required for INDIVIDUAL)

lastName string body

Last name (required for INDIVIDUAL)

companyName string body

Company name (required for CORPORATE)

isBeneficialOwner boolean body

Whether this is a beneficial owner (25%+ ownership)

isPEP boolean body

Politically Exposed Person status

Code Examples

cURL
bash
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);
Response example
201
json
{
  "success": true,
  "data": {
    "shareholderId": "sh_11111",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List Shareholders (v2)

Endpoint

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

Code Examples

cURL
bash
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}%`);
});
Response example
200
json
{
  "success": true,
  "data": {
    "shareholders": [
      {
        "shareholderId": "sh_12345",
        "type": "INDIVIDUAL",
        "firstName": "Max",
        "lastName": "Owner",
        "ownershipPercentage": 51.0,
        "isBeneficialOwner": true,
        "status": "VERIFIED"
      }
    ]
  }
}

Remove Shareholder (v2)

Endpoint

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

Code Examples

cURL
bash
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"
Response example
204
json
{
  "success": true
}

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

FieldIndividual ShareholderCorporate Shareholder
RequiredfirstName, lastName, dateOfBirth, nationalitycompanyName, registrationNumber, country
OwnershipownershipPercentage, numberOfSharesownershipPercentage, numberOfShares
IdentityPassport/ID numberTax ID, incorporation docs
ContactPersonal email, phoneContact person details
Due DiligencePEP 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 ClassDescriptionVoting Rights
ORDINARYStandard common sharesYes
PREFERENCEPreference shares with priority dividendsUsually limited
REDEEMABLECan be bought back by companyYes or No

Response Codes

CodeDescription
200Shareholders retrieved/updated successfully
201Shareholder added successfully
204Shareholder removed successfully
400Invalid request data or ownership validation failed
409Ownership total does not equal 100%
404Organization or shareholder not found
500Internal 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 document.

Standard Headers

Complete HTTP headers reference

Organization Registration

Register new organizations

Directors

Manage organization directors

Employees

Manage organization employees

Failed to load openapi.yaml: No number after minus sign in JSON at position 1 (line 1 column 2)

Type to search…

↑↓ navigate ↵ open esc close