FinHub
Open Developer Portal

Phase 2: Personnel Management

Add directors, shareholders, and employees to the organization

Phase 2: Personnel Management

Personnel must be added AFTER organization registration. Each person added also creates an individual customer record with login credentials.

Personnel Types

TypeDescriptionCreates Individual Record
DirectorsBoard members (verification required)✅ Yes
ShareholdersOwnership stakeholders✅ Yes (for individuals)
EmployeesOperations staff with specific roles✅ Yes

Add Director

Directors are automatically created as individual customers with temporary passwords.

Endpoint: POST /api/v2.1/customer/organization/{organizationId}/director

Headers:

http
Authorization: Bearer {admin-jwt-token}
Content-Type: application/json

Request Body:

json
{
  "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
  "email": "director@acme-corp.com",
  "firstName": "Michael",
  "middleName": "Robert",
  "lastName": "Brown",
  "dateOfBirth": "1970-09-25",
  "nationality": "GB",
  "phoneNumber": "+442071234572",
  "position": "Board Director",
  "directorType": "NON_EXECUTIVE",
  "appointmentDate": "2010-06-01",
  "isPEP": false,
  "ownershipPercentage": 0,
  "address": {
    "street": "321 Director Avenue",
    "city": "London",
    "postalCode": "EC3A 1BB",
    "country": "GB"
  },
  "identificationDocument": {
    "type": "PASSPORT",
    "number": "GB987654321",
    "issuingCountry": "GB",
    "expiryDate": "2030-12-31"
  }
}

Status: 200 OK

json
{
  "code": 200,
  "message": "Director added successfully",
  "data": {
    "organization": {
      "id": "org-dir-bb0e8400-e29b-41d4-a716-446655440140",
      "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
      "email": "director@acme-corp.com",
      "firstName": "Michael",
      "lastName": "Brown",
      "position": "Board Director",
      "directorType": "NON_EXECUTIVE",
      "appointmentDate": "2010-06-01",
      "status": "ACTIVE",
      "verificationStatus": "PENDING"
    },
    "individual": {
      "id": "ind-cc0e8400-e29b-41d4-a716-446655440141",
      "email": "director@acme-corp.com",
      "firstName": "Michael",
      "lastName": "Brown",
      "username": "director@acme-corp.com",
      "password": "Auto-Generated-P@ssw0rd456",
      "status": "ACTIVE",
      "linkedOrganization": "org-880e8400-e29b-41d4-a716-446655440110"
    }
  }
}

Key IDs Created:

  • Director’s individual customer ID
  • Director’s user ID
  • Temporary password (should be changed on first login)

Director Types

TypeDescription
EXECUTIVEFull-time executive director
NON_EXECUTIVEPart-time non-executive director
MANAGINGManaging director
CHAIRMANBoard chairman

Add Shareholders (Bulk)

Shareholders can be added in bulk using an array.

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

Request Body (Array):

json
[
  {
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
    "name": "Investment Fund Alpha Ltd",
    "shareholderType": "CORPORATE",
    "ownershipPercentage": 55.0,
    "numberOfShares": 5500,
    "shareClass": "ORDINARY",
    "votingRights": true,
    "registrationNumber": "REG-FUND-001",
    "taxId": "TAX-FUND-001",
    "country": "GB",
    "address": {
      "street": "100 Investment Street",
      "city": "London",
      "postalCode": "EC4A 1BB",
      "country": "GB"
    },
    "contactPerson": {
      "name": "Fund Manager",
      "email": "manager@investment-alpha.com",
      "phone": "+442071234580"
    }
  },
  {
    "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
    "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
    "name": "John Investor",
    "shareholderType": "INDIVIDUAL",
    "ownershipPercentage": 45.0,
    "numberOfShares": 4500,
    "shareClass": "ORDINARY",
    "votingRights": true,
    "dateOfBirth": "1965-04-12",
    "nationality": "GB",
    "identificationDocument": {
      "type": "PASSPORT",
      "number": "GB123789456",
      "issuingCountry": "GB"
    },
    "address": {
      "street": "200 Investor Road",
      "city": "London",
      "postalCode": "EC5A 1BB",
      "country": "GB"
    }
  }
]

Status: 200 OK

json
{
  "code": 200,
  "message": "Shareholders added successfully",
  "data": {
    "count": 2,
    "shareholders": [
      {
        "id": "share-dd0e8400-e29b-41d4-a716-446655440150",
        "name": "Investment Fund Alpha Ltd",
        "shareholderType": "CORPORATE",
        "ownershipPercentage": 55.0
      },
      {
        "id": "share-ee0e8400-e29b-41d4-a716-446655440151",
        "name": "John Investor",
        "shareholderType": "INDIVIDUAL",
        "ownershipPercentage": 45.0
      }
    ],
    "totalOwnership": 100.0,
    "validationStatus": "VALID"
  }
}

Shareholder Types

TypeDescription
INDIVIDUALPersonal shareholder
CORPORATECompany shareholder

Share Classes

ClassDescription
ORDINARYStandard voting shares
PREFERENCEPreference shares with dividends
REDEEMABLERedeemable shares

Add Employee

Endpoint: POST /api/v2.1/customer/organization/{organizationId}/employee

Request Body:

json
{
  "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
  "email": "compliance@acme-corp.com",
  "firstName": "Sarah",
  "middleName": "Jane",
  "lastName": "Johnson",
  "dateOfBirth": "1985-06-10",
  "nationality": "GB",
  "phoneNumber": "+442071234571",
  "department": "Compliance",
  "position": "Chief Compliance Officer",
  "employeeNumber": "EMP001",
  "startDate": "2015-03-01",
  "roles": ["EMPLOYEE", "COMPLIANCE_OFFICER", "ADMIN_USER"],
  "permissions": [
    "VIEW_TRANSACTIONS",
    "INITIATE_VERIFICATION",
    "APPROVE_SMALL_TRANSACTIONS"
  ],
  "address": {
    "street": "789 Employee Street",
    "city": "London",
    "postalCode": "EC2A 1BB",
    "country": "GB"
  }
}

Status: 200 OK

json
{
  "code": 200,
  "message": "Employee added successfully with role validation",
  "data": {
    "organization": {
      "id": "org-emp-990e8400-e29b-41d4-a716-446655440130",
      "organizationId": "org-880e8400-e29b-41d4-a716-446655440110",
      "email": "compliance@acme-corp.com",
      "firstName": "Sarah",
      "lastName": "Johnson",
      "department": "Compliance",
      "position": "Chief Compliance Officer",
      "roles": ["EMPLOYEE", "COMPLIANCE_OFFICER", "ADMIN_USER"],
      "status": "ACTIVE",
      "createdAt": "2026-01-13T10:30:00.000Z"
    },
    "individual": {
      "id": "ind-aa0e8400-e29b-41d4-a716-446655440131",
      "email": "compliance@acme-corp.com",
      "firstName": "Sarah",
      "lastName": "Johnson",
      "username": "compliance@acme-corp.com",
      "password": "Auto-Generated-P@ssw0rd123",
      "status": "ACTIVE",
      "linkedOrganization": "org-880e8400-e29b-41d4-a716-446655440110"
    }
  }
}

Status: 400 Bad Request

json
{
  "code": 400,
  "message": "Missing required role 'ADMIN_USER' for BUSINESS_TYPE_CLIENT_TO_TENANT organization. At least one employee must have this role."
}

Employee Roles

RoleDescription
EMPLOYEEBase role for all employees
ADMIN_USERAdministrative access (required for first employee)
COMPLIANCE_OFFICERCompliance and verification access
TRANSACTION_APPROVERApprove transactions
OPERATIONS_MANAGEROperations management

Auto-Role Assignment

Roles can be auto-assigned based on department:

DepartmentAuto-Assigned Roles
ComplianceCOMPLIANCE_OFFICER
FinanceTRANSACTION_APPROVER
ManagementADMIN_USER
OperationsOPERATIONS_MANAGER

Get Organization Definitions

Endpoint: GET /api/v2.1/customer/organization/definitions

json
{
  "code": 200,
  "message": "Definitions retrieved successfully",
  "data": {
    "ORG_REQUIRED_FIELDS": {
      "mandatory": [
        "legalName",
        "businessType",
        "registrationNumber",
        "taxId",
        "incorporationDate",
        "registeredAddress"
      ]
    },
    "SHAREHOLDER_RULES": {
      "totalOwnership": {
        "mustEqual": 100,
        "message": "Total ownership must equal 100%"
      },
      "minimumShareholders": 1,
      "shareholderTypes": ["INDIVIDUAL", "CORPORATE"],
      "shareClasses": ["ORDINARY", "PREFERENCE", "REDEEMABLE"]
    }
  }
}

Next Step

After adding personnel, proceed to Phase 3: Verification for KYB verification.

Phase 3: Verification

Initiate KYB verification process

Type to search…

↑↓ navigate ↵ open esc close