Employees & Referrals API

Overview

The Employees & Referrals API provides operations for managing employee records and tracking customer referrals. It supports the full employee lifecycle — from creation and bulk upload through to referral code generation and referral tracking. Each employee is automatically assigned a unique referral code that can be used to link new customer registrations back to the referring staff member.

Available Commands

#	Command	Type	Description
1	CreateEmployeeCommand	Command	Create a new employee record
2	UpdateEmployeeCommand	Command	Update an existing employee record
3	RetrieveEmployeesListQuery	Query	List employees with filtering and pagination
4	RetrieveEmployeeByIdQuery	Query	Get a single employee by ID
5	UploadEmployeesCommand	Command	Bulk upload employees from an Excel file
6	RetrieveEmployeeReferralsQuery	Query	List referrals for a specific employee
7	CreateEmployeeReferralCommand	Command	Link a customer registration to an employee referral
8	SendEmployeeReferralCodeCommand	Command	Send referral code to employee's email

Common Request Pattern

All commands and queries are sent as a POST to the unified BPM endpoint:

POST /api/bpm/cmd
Content-Type: application/json
Authorization: Bearer {token}

Request body:

{
  "$type": "CommandOrQueryClassName",
  // ...command-specific fields
}

Common Response Pattern

Success:

{
  "success": true,
  "data": { },
  "message": "Operation completed successfully"
}

Error:

{
  "success": false,
  "data": null,
  "message": "Description of what went wrong",
  "errors": ["Detailed error 1", "Detailed error 2"]
}

Authentication

All Employees & Referrals API requests require a valid Bearer token in the Authorization header. Tokens are obtained via the authentication endpoint and must belong to a user with the appropriate employee management permissions.

Employee Lifecycle

When an employee is created (individually or via bulk upload), the system automatically generates a unique referralCode. This code can be shared with potential customers. When a customer registers using a referral code, the CreateEmployeeReferralCommand links that registration to the originating employee, enabling performance tracking and incentive calculations.

Quick Links

• Create Employee — Add a new employee record
• Update Employee — Modify an existing employee
• Retrieve Employees — List and filter employees
• Retrieve Employee by ID — Get a single employee
• Upload Employees — Bulk import from Excel
• Retrieve Referrals — List referrals for an employee
• Create Referral — Link a customer to a referral code