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}/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" : "[email protected] " , "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" : "[email protected] " , "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" : "[email protected] " , "firstName" : "Michael" , "lastName" : "Brown" , "username" : "[email protected] " , "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 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}/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" : "[email protected] " , "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 INDIVIDUALPersonal shareholder CORPORATECompany shareholder
Share Classes Class Description ORDINARYStandard voting shares PREFERENCEPreference shares with dividends REDEEMABLERedeemable shares
Add Employee Endpoint: POST /api/v2.1/customer/organization/{organizationId}/employeeRequest Body: { "tenantId" : "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" , "organizationId" : "org-880e8400-e29b-41d4-a716-446655440110" , "email" : "[email protected] " , "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" : "[email protected] " , "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" : "[email protected] " , "firstName" : "Sarah" , "lastName" : "Johnson" , "username" : "[email protected] " , "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 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:
Department Auto-Assigned Roles Compliance COMPLIANCE_OFFICERFinance TRANSACTION_APPROVERManagement ADMIN_USEROperations OPERATIONS_MANAGER
Get Organization Definitions 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
