> ## 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.
# 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
| Type | Description | Creates Individual Record |
| ---------------- | ------------------------------------- | ------------------------- |
| **Directors** | Board members (verification required) | ✅ Yes |
| **Shareholders** | Ownership stakeholders | ✅ Yes (for individuals) |
| **Employees** | Operations staff with specific roles | ✅ Yes |
**First Employee Rule:** The first employee added to an organization MUST have the `ADMIN_USER` role. Without this role, the request will fail with a 400 error.
***
## Add Director
Directors are automatically created as individual customers with temporary passwords.
**Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/director`
**Headers:**
```http theme={null}
Authorization: Bearer {admin-jwt-token}
Content-Type: application/json
```
**Request Body:**
```json theme={null}
{
"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 theme={null}
{
"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
| Type | Description |
| --------------- | -------------------------------- |
| `EXECUTIVE` | Full-time executive director |
| `NON_EXECUTIVE` | Part-time non-executive director |
| `MANAGING` | Managing director |
| `CHAIRMAN` | Board 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 theme={null}
[
{
"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 theme={null}
{
"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
| Type | Description |
| ------------ | -------------------- |
| `INDIVIDUAL` | Personal shareholder |
| `CORPORATE` | Company shareholder |
### Share Classes
| Class | Description |
| ------------ | -------------------------------- |
| `ORDINARY` | Standard voting shares |
| `PREFERENCE` | Preference shares with dividends |
| `REDEEMABLE` | Redeemable shares |
***
## Add Employee
**Endpoint:** `POST /api/v2.1/customer/organization/{organizationId}/employee`
**Request Body:**
```json theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"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
| Role | Description |
| ---------------------- | --------------------------------------------------- |
| `EMPLOYEE` | Base role for all employees |
| `ADMIN_USER` | Administrative access (required for first employee) |
| `COMPLIANCE_OFFICER` | Compliance and verification access |
| `TRANSACTION_APPROVER` | Approve transactions |
| `OPERATIONS_MANAGER` | Operations management |
### Auto-Role Assignment
Roles can be auto-assigned based on department:
| Department | Auto-Assigned Roles |
| ---------- | ---------------------- |
| Compliance | `COMPLIANCE_OFFICER` |
| Finance | `TRANSACTION_APPROVER` |
| Management | `ADMIN_USER` |
| Operations | `OPERATIONS_MANAGER` |
***
## Get Organization Definitions
**Endpoint:** `GET /api/v2.1/customer/organization/definitions`
```json theme={null}
{
"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.
Initiate KYB verification process