Documentation

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

API: List Employee Schedules

The purpose of this API is to retrieve employee schedules within a specified date range, with optional filters.

Request

API Name Schedule
URL https://your_account.modulus.biz/api/hr/v1/Schedule
Method GET
Source Third Party Server
Recipient modulus® Server
Content Type application/json
Accept application/json

Request Headers

Header Required Description
Authorization Yes Bearer token for authentication.
Format: Bearer <token>

Query String Parameters

Parameter Required Type Description
date_from Yes Date Start date in format YYYY-MM-DD.
date_to Yes Date End date in format YYYY-MM-DD. Must be later than date_from.
employee_code No Number Restricts result to a specific employee.
has_punch No Boolean Set to 1 to include only employees who have punch-in/out records.
include_schedule No Boolean If 1, includes full schedule details for each employee.
min_expected_minutes No Number Filters employees with expected working minutes above this value.
max_expected_minutes No Number Filters employees with expected working minutes below this value.
page_number No Number Page number of the result set. Default = 1.
page_size No Number Number of records per page. Default = 50.

Responses

HTTP Status result title message object
Success Responses
200 OK true Success Schedules listed successfully. 
{
"meta_data": {
  "page_count": 1,
  "page_number": 1,
  "page_size": 50,
  "record_count": 1
},
"data": [
  {
    "employee_code": "0001",
    "department_name": "QA/QC",
    "location_name": "Cairo HQ",
    "position_name": "Manager QC",
    "schedules": [
      {
        "date": "2025-01-05",
        "attended_from": "2025-01-05 09:00",
        "attended_to": "2025-01-05 17:00",
        "expected_from": "2025-01-05 09:00",
        "expected_to": "2025-01-05 17:00",
        "shift_nature": "Attended"
      }
    ]
  }
]
}
Failure Responses
400 Bad Request false Error X is required. null

Example 1

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Schedule?date_from=2025-01-01&date_to=2025-01-02&include_schedule=1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer y78hewy2387898978732814jewjkj32u489u'
200 OK 
{
"result": true,
"title": "Success",
"message": "Schedules listed successfully.",
"object": {
  "meta_data": {
    "page_count": 1,
    "page_number": 1,
    "page_size": 50,
    "record_count": 1
  },
  "data": [
    {
      "employee_code": "0001",
      "department_name": "QA/QC",
      "location_name": "Cairo HQ",
      "position_name": "Manager QC",
      "schedules": [
        {
          "date": "2025-01-01",
          "attended_from": "2025-01-01 09:00",
          "attended_to": "2025-01-01 17:00",
          "expected_from": "2025-01-01 09:00",
          "expected_to": "2025-01-01 17:00",
          "shift_nature": "Attended"
        }
      ]
    }
  ]
}
}

Example 2

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Schedule?date_from=2025-01-01&date_to=2025-01-02&include_schedule=1&page_number=2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer y78hewy2387898978732814jewjkj32u489u'
200 OK 
{
"result": true,
"title": "Success",
"message": "No data found match your conditions.",
"object": null
}

Example 3

Request 
curl --request GET 'https://your_account.modulus.biz/api/hr/v1/Schedule?date_from=2025-01-01' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer y78hewy2387898978732814jewjkj32u489u'
400 Bad Request 
{
"result": false,
"title": "Error",
"message": "date_to is required",
"object": null
}