Organization Shareholders API

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/customer/organization/{organizationId}/shareholders \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "ownershipPercentage": 123,
  "firstName": "<string>",
  "lastName": "<string>",
  "companyName": "<string>",
  "isBeneficialOwner": true,
  "isPEP": true
}
'

{
  "success": true,
  "data": {
    "shareholderId": "sh_11111",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

POST

api

v2.1

customer

organization

{organizationId}

shareholders

Organization Shareholders API

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/customer/organization/{organizationId}/shareholders \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "ownershipPercentage": 123,
  "firstName": "<string>",
  "lastName": "<string>",
  "companyName": "<string>",
  "isBeneficialOwner": true,
  "isPEP": true
}
'

{
  "success": true,
  "data": {
    "shareholderId": "sh_11111",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Organization Shareholders API

APIs for managing beneficial owners and shareholders of business organizations.

Base URL: https://sandbox.finhub.cloud

Available Operations

Add Shareholders

POST /v2.1/.../shareholders

List Shareholders

GET /v2/organizations/{id}/shareholders

Remove Shareholder

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

Note: List and Remove operations use the /api/v2/ endpoint path, while Add uses /api/v2.1/.

Add Shareholders (v2.1)

Adds one or more shareholders to the specified organization.

For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.

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

required

Organization identifier

type

string

required

Shareholder type: INDIVIDUAL or CORPORATE

ownershipPercentage

number

required

Ownership percentage (0-100)

firstName

string

First name (required for INDIVIDUAL)

lastName

string

Last name (required for INDIVIDUAL)

companyName

string

Company name (required for CORPORATE)

isBeneficialOwner

boolean

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

isPEP

boolean

Politically Exposed Person status

Code Examples

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"
    }
  }'

{
  "success": true,
  "data": {
    "shareholderId": "sh_11111",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List Shareholders (v2)

Retrieves all shareholders for an organization with ownership percentages.

Endpoint

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

Code Examples

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"

{
  "success": true,
  "data": {
    "shareholders": [
      {
        "shareholderId": "sh_12345",
        "type": "INDIVIDUAL",
        "firstName": "Max",
        "lastName": "Owner",
        "ownershipPercentage": 51.0,
        "isBeneficialOwner": true,
        "status": "VERIFIED"
      }
    ]
  }
}

Remove Shareholder (v2)

Removes a shareholder from the organization (requires ADMIN_USER role).

Endpoint

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

Code Examples

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"

{
  "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

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%:

// 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 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:

{
  "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

Directors

Manage organization directors

Employees

Manage organization employees

⌘I

​Organization Shareholders API

​Available Operations

Add Shareholders

List Shareholders

Remove Shareholder

​Add Shareholders (v2.1)

​Before You Start

​Endpoint

​Request

​Code Examples

​List Shareholders (v2)

​Endpoint

​Code Examples

​Remove Shareholder (v2)

​Endpoint

​Code Examples

​Beneficial Ownership Rules

​Shareholder Types Comparison

​Ownership Validation (100% Rule)

​Share Classes

​Response Codes

​Common Validation Errors

​Error: Ownership Total Mismatch

​Error: Beneficial Owner Not Declared

​Error: Missing Required Fields

​API Schema Reference

​Related Endpoints

Standard Headers

Organization Registration

Directors

Employees

Organization Shareholders API

Available Operations

Add Shareholders (v2.1)

Before You Start

Endpoint

Request

Code Examples

List Shareholders (v2)

Endpoint

Code Examples

Remove Shareholder (v2)

Endpoint

Code Examples

Beneficial Ownership Rules

Shareholder Types Comparison

Ownership Validation (100% Rule)

Share Classes

Response Codes

Common Validation Errors

Error: Ownership Total Mismatch

Error: Beneficial Owner Not Declared

Error: Missing Required Fields

API Schema Reference

Related Endpoints