Documentation

Employees

Sync and manage employees from your third-party application.

Requires scope: employees

List/get employees, and create/update staff needed for integrations.

Allowed create roles: staff, manager, hr, it-admin. Password is optional — if omitted, a temporary password is returned once.

Endpoints

GET/api/v1/integrations/employeesBearer auth

List employees (paginated)

Query: page, limit, search

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "employees": [
      {
        "id": "665f1a2b3c4d5e6f7a8b9c0d",
        "employeeId": "EMP001",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "email": "ada@acme.com",
        "phone": "+919999999999",
        "role": "staff",
        "employmentStatus": "active",
        "departmentId": "665f1a2b3c4d5e6f7a8b9c11",
        "designationId": null,
        "joiningDate": "2026-04-01T00:00:00.000Z",
        "isActive": true
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
  }
}

POST/api/v1/integrations/employeesBearer auth

Create an employee

Request body

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "ada@acme.com",
  "phone": "+919999999999",
  "role": "staff",
  "department": "<departmentId>",
  "joiningDate": "2026-04-01",
  "employmentType": "full-time",
  "employmentStatus": "active"
}

Example response

{
  "success": true,
  "status": 201,
  "message": "Employee created",
  "data": {
    "employee": {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "employeeId": "EMP001",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@acme.com",
      "role": "staff",
      "isActive": true
    },
    "temporaryPassword": "Tx9kP2mQ"
  }
}

GET/api/v1/integrations/employees/:idBearer auth

Get one employee

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "employee": {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "employeeId": "EMP001",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@acme.com",
      "phone": "+919999999999",
      "role": "staff",
      "employmentStatus": "active",
      "departmentId": "665f1a2b3c4d5e6f7a8b9c11",
      "isActive": true
    }
  }
}

PUT/api/v1/integrations/employees/:idBearer auth

Update an employee

Request body

{
  "firstName": "Ada",
  "phone": "+919888888888",
  "department": "<departmentId>",
  "employmentStatus": "active",
  "isActive": true
}

Example response

{
  "success": true,
  "status": 200,
  "message": "Employee updated",
  "data": {
    "employee": {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "firstName": "Ada",
      "phone": "+919888888888",
      "employmentStatus": "active",
      "isActive": true
    }
  }
}