Upload Employees (Bulk)

Overview

Bulk uploads employee records from a structured JSON array. The system processes each record and either creates a new employee or updates an existing one based on the staffId field. Each newly created employee is automatically assigned a unique referral code.

A legacy Base64-encoded Excel file path is also supported for backward compatibility.

Command Details

• Command: UploadEmployeesCommand
• Type: Command (write operation)

API Endpoint

POST /api/bpm/cmd

Request Structure (Preferred)

Field	Type	Required	Description
$type	string	Yes	Must be UploadEmployeesCommand
employees	array	Yes*	Array of employee objects (see fields below)

Employee Object Fields

Field	Type	Required	Description
staffId	string	Yes	Unique staff identifier (used to match existing records)
email	string	Yes	Employee email address
title	string	No	Title (e.g., Mr, Mrs, Dr)
firstName	string	Yes	Employee first name
lastName	string	Yes	Employee last name
middleName	string	No	Employee middle name
branch	string	No	Branch name or code
role	string	No	Employee role or position
isAccountOfficer	boolean	No	Whether the employee is an account officer (default: false)
canReferCustomer	boolean	No	Whether the employee can refer customers (default: true)

info

• If a staffId already exists in the system, the corresponding employee record will be updated with the new values.
• If a staffId does not exist, a new employee will be created with an auto-generated referral code.

Try It Out

POST/api/bpm/cmdUploadEmployeesCommand

Base URL

Bearer Token

Request Body

{ "cmd": "UploadEmployeesCommand", "data": { "employees": [ { "staffId": "EMP001", "email": "john.doe@example.com", "title": "Mr", "firstName": "John", "lastName": "Doe", "middleName": "", "branch": "Head Office", "role": "Manager", "isAccountOfficer": false, "canReferCustomer": true }, { "staffId": "EMP002", "email": "jane.smith@example.com", "title": "Mrs", "firstName": "Jane", "lastName": "Smith", "middleName": "A", "branch": "Lagos Branch", "role": "Officer", "isAccountOfficer": true, "canReferCustomer": true } ] } }

Response Structure

Success:

{
  "isSuccessful": true,
  "message": "Upload complete. Created: 2, Updated: 0, Errors: 0.",
  "data": {
    "created": 2,
    "updated": 0,
    "errorCount": 0,
    "errors": []
  }
}

Partial errors:

{
  "isSuccessful": true,
  "message": "Upload complete. Created: 15, Updated: 5, Errors: 5.",
  "data": {
    "created": 15,
    "updated": 5,
    "errorCount": 5,
    "errors": [
      "Record 3: StaffId and Email are required.",
      "Record 7: Email (john@example.com) already belongs to another employee.",
      "Record 10: FirstName and LastName are required."
    ]
  }
}

Legacy: Base64 Excel Upload

For backward compatibility, you can also send a Base64-encoded Excel file instead of a JSON array.

Field	Type	Required	Description
$type	string	Yes	Must be UploadEmployeesCommand
fileBase64	string	Yes*	Base64-encoded Excel file content

*Either employees or fileBase64 must be provided. If both are present, employees takes precedence.

Expected Excel Columns

Column	Position	Required	Description
StaffId	1	Yes	Unique staff identifier
Email	2	Yes	Employee email address
Title	3	No	Title (e.g., Mr, Mrs, Dr)
FirstName	4	Yes	Employee first name
LastName	5	Yes	Employee last name
MiddleName	6	No	Employee middle name
Branch	7	No	Branch name or code
Role	8	No	Employee role or position

Related Operations

• Create Employee — Create a single employee
• Retrieve Employees — List all employees