Skip to main content
POST
https://sandbox.finhub.cloud
/
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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Organization-ID: org_12345"

{
  "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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Organization-ID: org_12345" \
  -H "X-User-Roles: ADMIN_USER"

{
  "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%: 
// 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: 
{
  "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