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.

Request
Response

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

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

Request Body:

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

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

Request
Response

Endpoint: POST /api/v2.1/customer/organization/{organizationId}/shareholdersRequest Body (Array):

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

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

Class	Description
`ORDINARY`	Standard voting shares
`PREFERENCE`	Preference shares with dividends
`REDEEMABLE`	Redeemable shares

Add Employee

Request
Success Response
Error - Missing ADMIN_USER

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

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

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

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

Request
Response

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

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

​Phase 2: Personnel Management

​Personnel Types

​Add Director

​Director Types

​Add Shareholders (Bulk)

​Shareholder Types

​Share Classes

​Add Employee

​Employee Roles

​Auto-Role Assignment

​Get Organization Definitions

​Next Step

Phase 3: Verification

Phase 2: Personnel Management

Personnel Types

Add Director

Director Types

Add Shareholders (Bulk)

Shareholder Types

Share Classes

Add Employee

Employee Roles

Auto-Role Assignment

Get Organization Definitions

Next Step