Skip to main content
The Employees API provides endpoints for creating, updating, and managing employee accounts, including PIN authentication and role management.

​
Get all employees

Retrieve a list of all employees in the system. 
GET /api/employees

​
Query parameters

​
includeInactive
boolean
default:"false"
Include inactive employees in the results

​
Response

Returns an array of employee objects.
​
id
integer
Unique employee identifier
​
employeeId
string
Employee ID (max 10 characters)
​
name
string
Employee full name (max 100 characters)
​
role
string
Employee role: Manager, Cashier, or Inventory
​
isManager
boolean
Legacy manager status flag
​
isActive
boolean
Whether the employee account is active
​
createdDate
string
ISO 8601 timestamp of account creation

​
Example request

curl -X GET "https://api.example.com/api/employees?includeInactive=false" \
  -H "Content-Type: application/json"

​
Example response

[
  {
    "id": 1,
    "employeeId": "EMP001",
    "name": "John Doe",
    "role": "Manager",
    "isManager": true,
    "isActive": true,
    "createdDate": "2024-01-15T08:30:00Z"
  },
  {
    "id": 2,
    "employeeId": "EMP002",
    "name": "Jane Smith",
    "role": "Cashier",
    "isManager": false,
    "isActive": true,
    "createdDate": "2024-01-16T09:15:00Z"
  }
]

​
Get employee by ID

Retrieve details of a specific employee. 
GET /api/employees/{id}

​
Path parameters

​
id
integer
required
Employee ID

​
Example request

curl -X GET "https://api.example.com/api/employees/1" \
  -H "Content-Type: application/json"

​
Response

Returns a single employee object (same structure as above).

​
Create employee

Create a new employee account with PIN authentication. 
POST /api/employees

​
Request body

​
employeeId
string
required
Unique employee identifier (max 10 characters)
​
name
string
required
Employee full name (max 100 characters)
​
pin
string
required
6-digit numeric PIN for authentication (will be hashed)
​
role
string
required
Employee role: Manager, Cashier, or Inventory
​
isActive
boolean
default:"true"
Whether the account should be active

​
Example request

curl -X POST "https://api.example.com/api/employees" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin" \
  -d '{
    "employeeId": "EMP003",
    "name": "Bob Johnson",
    "pin": "123456",
    "role": "Cashier",
    "isActive": true
  }'

​
Validation rules

  • Employee ID cannot be empty and must be unique
  • Name cannot be empty
  • PIN must be exactly 6 digits
  • PIN must contain only numbers
  • Role must be one of: Manager, Cashier, Inventory

​
Response

Returns the created employee object with hashed PIN.

​
Update employee

Update an existing employee’s details. 
PUT /api/employees/{id}

​
Path parameters

​
id
integer
required
Employee ID to update

​
Request body

Same as create employee, but all fields are optional except id (which must match the path parameter).

​
Example request

curl -X PUT "https://api.example.com/api/employees/3" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin" \
  -d '{
    "id": 3,
    "employeeId": "EMP003",
    "name": "Bob Johnson",
    "pin": "hashed_value",
    "role": "Inventory",
    "isActive": true
  }'

​
Deactivate employee

Deactivate an employee account (soft delete). 
PUT /api/employees/{id}/deactivate

​
Path parameters

​
id
integer
required
Employee ID to deactivate

​
Example request

curl -X PUT "https://api.example.com/api/employees/3/deactivate" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin"

​
Activate employee

Reactivate a previously deactivated employee account. 
PUT /api/employees/{id}/activate

​
Path parameters

​
id
integer
required
Employee ID to activate

​
Example request

curl -X PUT "https://api.example.com/api/employees/3/activate" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin"

​
Reset employee PIN

Reset an employee’s PIN for security purposes. 
PUT /api/employees/{id}/reset-pin

​
Path parameters

​
id
integer
required
Employee ID

​
Request body

​
newPin
string
required
New 6-digit numeric PIN

​
Example request

curl -X PUT "https://api.example.com/api/employees/3/reset-pin" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin" \
  -d '{
    "newPin": "654321"
  }'

​
Response

{
  "message": "PIN reset successfully"
}

​
Authentication headers

All employee management endpoints log activity and require authentication headers:
  • X-User-Id: The ID of the user performing the action
  • X-User-Name: The name of the user performing the action
These headers are used for audit logging in the user activity system.

Build docs developers (and LLMs) love

Get started for freeTalk to us