Employees API

The Employees module manages your workforce — personal details, department assignments, job positions, and employment contracts. It integrates with Attendance, Payroll, Time Off, and Appraisals modules.

---

Endpoints

Method	Path	Description
GET	/api/employees	List employees (paginated)
POST	/api/employees	Create an employee
GET	/api/employees/:id	Get an employee
PATCH	/api/employees/:id	Update an employee
DELETE	/api/employees/:id	Archive an employee
GET	/api/employees/departments	List departments
POST	/api/employees/departments	Create a department
GET	/api/employees/:id/contracts	List contracts for an employee
POST	/api/employees/:id/contracts	Add a contract
GET	/api/employees/:id/time-off	List approved leave
GET	/api/employees/:id/attendance	List attendance records

---

List Employees

GET /api/employees?page=1&limit=20&department=engineering&status=active&search=john

Query Parameters

Parameter	Type	Description
page	number	Page number
limit	number	Items per page (max: 100)
search	string	Search by name or job title
department	string	Filter by department name or ID
status	active | archived	Employment status (default: active)
sortBy	string	name, department, hireDate

Response

{
  "data": [
    {
      "id": "018ecccc-abcd-7000-8000-000000000001",
      "name": "Jane Smith",
      "email": "jane.smith@acme.com",
      "jobTitle": "Senior Developer",
      "department": {
        "id": "018ecccc-dddd-7000-8000-000000000001",
        "name": "Engineering"
      },
      "manager": {
        "id": "018ecccc-eeee-7000-8000-000000000001",
        "name": "Bob Johnson"
      },
      "hireDate": "2024-03-01",
      "status": "active",
      "createdAt": "2024-03-01T08:00:00Z"
    }
  ],
  "meta": { "total": 45, "page": 1, "limit": 20, "totalPages": 3 }
}

---

Create an Employee

POST /api/employees
Content-Type: application/json
Authorization: Bearer eco_live_...

Request Body

{
  "name": "Alice Wong",
  "email": "alice.wong@acme.com",
  "jobTitle": "Product Manager",
  "departmentId": "018ecccc-dddd-7000-8000-000000000001",
  "managerId": "018ecccc-eeee-7000-8000-000000000001",
  "hireDate": "2026-04-01",
  "phone": "+1-555-333-4444",
  "address": {
    "city": "New York",
    "country": "US"
  }
}

Required fields: name, email, jobTitle, hireDate

---

Departments

List Departments

GET /api/employees/departments

[
  {
    "id": "018ecccc-dddd-7000-8000-000000000001",
    "name": "Engineering",
    "manager": { "id": "...", "name": "Bob Johnson" },
    "employeeCount": 12
  }
]

Create a Department

POST /api/employees/departments
Content-Type: application/json

{
  "name": "Customer Success",
  "managerId": "018ecccc-abcd-7000-8000-000000000001"
}

---

Contracts

List Contracts

GET /api/employees/018ecccc-abcd-7000-8000-000000000001/contracts

[
  {
    "id": "018ecccc-ffff-7000-8000-000000000001",
    "type": "full_time",
    "startDate": "2024-03-01",
    "endDate": null,
    "salary": 8500000,
    "currency": "usd",
    "status": "active"
  }
]

Note: salary is in smallest currency unit (cents).

Add a Contract

POST /api/employees/018ecccc-abcd-7000-8000-000000000001/contracts
Content-Type: application/json

{
  "type": "full_time",
  "startDate": "2026-04-01",
  "salary": 9000000,
  "currency": "usd"
}

Contract types: full_time, part_time, contractor, intern

---

Status Codes

Code	Scenario
200	Get or list succeeded
201	Employee, department, or contract created
204	Employee archived
404	Employee or department not found
409	Email already used by another employee
422	Validation failure (e.g., invalid hire date)