Documentation

  2. Home
  4. Docs
  6. Documentation
  8. Personnel APIs – V1
  10. API: List Employees

API: List Employees

The purpose of this API is to retrieve a paginated list of employees, with optional filters and additional personal and employment information. If groups is omitted, only employee_code, full_name, and short_name are returned.

Request

Property Value
API Name Employee
URL https://your_account.modulus.biz/api/hr/v1/Employee
Method GET
Source Third Party Server
Recipient modulus® Server
Accept application/json
Authentication Bearer token

Request Headers

Header Required Description
Authorization Yes Bearer token for authentication. Format: Bearer <token>
Accept Yes application/json

Query String Parameters

Parameter Required Type Description
employee_code No String Filter by employee code.
employment_status No String Filter by employment status. Possible values: Working, Terminated, Resigned.
location_id No Integer Filter by location ID.
position_id No Integer Filter by position ID.
department_id No Integer Filter by department ID.
direct_head_code No String Filter employees reporting directly to the specified employee code.
groups No String Comma-separated information groups: personal_info, employment_info. Omit to return root fields only.
page_number No Integer Page number. Default = 1.
page_size No Integer Records per page. Default = 50; recommended maximum = 500.

When multiple employee filters are supplied, they are combined using AND logic. Employee codes are strings; preserve leading zeros.

Information Groups

Group Description
personal_info Gender, date of birth, nationality, religion, marital status, military status, and education.
employment_info Employment status, join date, layoff date, location, position, department, contract type, working days, working hours, attendance scheme, and direct head code.

Example: groups=personal_info,employment_info. Unrequested groups are omitted completely, rather than returned as null.

Responses

HTTP Status result title message object
200 OK true Success Employees listed successfully. 
{
  "meta_data": {
    "page_count": 3,
    "page_number": 1,
    "page_size": 50,
    "record_count": 127
  },
  "data": [
    {
      "employee_code": "0001",
      "full_name": "Ahmed Mohamed Hassan",
      "short_name": "Ahmed Hassan",
      "personal_info": {
        "gender": "Male",
        "date_of_birth": "1990-05-15",
        "nationality": "Egyptian",
        "religion": "Muslim",
        "marital_status": "Married",
        "military_status": "Completed",
        "education": "Bachelor of Commerce"
      },
      "employment_info": {
        "employment_status": "Working",
        "join_date": "2020-01-15",
        "layoff_date": null,
        "location": {
          "id": 3,
          "name": "Cairo HQ"
        },
        "position": {
          "id": 17,
          "name": "Senior Accountant"
        },
        "department": {
          "id": 12,
          "name": "Finance"
        },
        "contract_type": {
          "id": 1,
          "name": "Full Time"
        },
        "working_days": 5,
        "working_hours": 40,
        "attendance_scheme": {
          "id": 4,
          "name": "Standard Office Hours"
        },
        "direct_head_code": "0025"
      }
    }
  ]
}
200 OK (No Matches) true Success No employees found matching your conditions. 
{
  "meta_data": {
    "page_count": 0,
    "page_number": 1,
    "page_size": 50,
    "record_count": 0
  },
  "data": []
}
400 Bad Request false Invalid Request Invalid information group: payroll_info. 
null

Response Structure

Field Type Description
result Boolean Indicates whether the request was processed successfully.
title String Short response title.
message String Human-readable response message.
object Object / null Response payload containing meta_data and data for successful list requests.

Pagination Metadata

Field Type Description
page_count Integer Total number of pages.
page_number Integer Current page number.
page_size Integer Requested records per page.
record_count Integer Total records matching supplied filters.

Root Employee Fields

Field Type Nullable Description
employee_code String No Employee code. Always returned. Preserve leading zeros.
full_name String No Employee full name. Always returned.
short_name String Yes Employee short/display name. Always returned.

Personal Information Fields

Field Type Nullable Description
gender String Yes Employee gender.
date_of_birth Date Yes Date of birth in YYYY-MM-DD format.
nationality String Yes Employee nationality.
religion String Yes Employee religion.
marital_status String Yes Employee marital status.
military_status String Yes Employee military service status.
education String Yes Employee education information.

Employment Information Fields

Field Type Nullable Description
employment_status String No Current employment status.
join_date Date Yes Join date in YYYY-MM-DD format.
layoff_date Date Yes Layoff/termination date in YYYY-MM-DD format.
location Object Yes Assigned location as {id, name}.
position Object Yes Assigned position as {id, name}.
department Object Yes Assigned department as {id, name}.
contract_type Object Yes Assigned contract type as {id, name}.
working_days Number Yes Configured working days.
working_hours Number Yes Configured working hours.
attendance_scheme Object Yes Attendance scheme as {id, name}.
direct_head_code String Yes Employee code of direct head/supervisor.

Reference Objects

The location, position, department, contract_type, and attendance_scheme fields use reference objects with an integer id and string name. Unassigned references are returned as null.

{
  "id": 12,
  "name": "Finance"
}

Example 1 – Root Information Only

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Employee?page_number=1&page_size=50' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'
200 OK 
{
  "result": true,
  "title": "Success",
  "message": "Employees listed successfully.",
  "object": {
    "meta_data": {
      "page_count": 1,
      "page_number": 1,
      "page_size": 50,
      "record_count": 1
    },
    "data": [
      {
        "employee_code": "0001",
        "full_name": "Ahmed Mohamed Hassan",
        "short_name": "Ahmed Hassan"
      }
    ]
  }
}

Example 2 – Personal and Employment Information

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Employee?groups=personal_info,employment_info&page_number=1&page_size=50' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'
200 OK 
{
  "result": true,
  "title": "Success",
  "message": "Employees listed successfully.",
  "object": {
    "meta_data": {
      "page_count": 3,
      "page_number": 1,
      "page_size": 50,
      "record_count": 127
    },
    "data": [
      {
        "employee_code": "0001",
        "full_name": "Ahmed Mohamed Hassan",
        "short_name": "Ahmed Hassan",
        "personal_info": {
          "gender": "Male",
          "date_of_birth": "1990-05-15",
          "nationality": "Egyptian",
          "religion": "Muslim",
          "marital_status": "Married",
          "military_status": "Completed",
          "education": "Bachelor of Commerce"
        },
        "employment_info": {
          "employment_status": "Working",
          "join_date": "2020-01-15",
          "layoff_date": null,
          "location": {
            "id": 3,
            "name": "Cairo HQ"
          },
          "position": {
            "id": 17,
            "name": "Senior Accountant"
          },
          "department": {
            "id": 12,
            "name": "Finance"
          },
          "contract_type": {
            "id": 1,
            "name": "Full Time"
          },
          "working_days": 5,
          "working_hours": 40,
          "attendance_scheme": {
            "id": 4,
            "name": "Standard Office Hours"
          },
          "direct_head_code": "0025"
        }
      }
    ]
  }
}

Example 3 – Filtered Employee List

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Employee?employment_status=Working&location_id=3&department_id=12&direct_head_code=0025&groups=employment_info&page_number=1&page_size=50' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'

Example 4 – Specific Employee

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Employee?employee_code=0001&groups=personal_info,employment_info' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'

Example 5 – No Matching Employees

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Employee?employee_code=NONEXISTENT' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'
200 OK 
{
  "result": true,
  "title": "Success",
  "message": "No employees found matching your conditions.",
  "object": {
    "meta_data": {
      "page_count": 0,
      "page_number": 1,
      "page_size": 50,
      "record_count": 0
    },
    "data": []
  }
}

Example 6 – Invalid Group

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Employee?groups=personal_info,payroll_info' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'
400 Bad Request 
{
  "result": false,
  "title": "Invalid Request",
  "message": "Invalid information group: payroll_info.",
  "object": null
}

Integration Notes

  • Use employee_code and direct_head_code as strings to preserve leading zeros.
  • Use location_id, position_id, and department_id to filter organizational assignments.
  • Contract type is returned in employment_info but is not currently exposed as a request filter.
  • When groups is omitted, only employee_code, full_name, and short_name are returned.
  • Requested groups are expanded for each employee; unrequested groups are omitted.
  • Use pagination metadata instead of assuming a response contains the full result set.