{"id":4778,"date":"2026-10-12T17:08:10","date_gmt":"2026-10-12T14:08:10","guid":{"rendered":"https:\/\/modulus.help\/kb\/docs\/documentation\/personnel-apis-v1\/api-list-attendance-logs\/"},"modified":"2026-10-12T18:23:38","modified_gmt":"2026-10-12T15:23:38","slug":"api-list-employees","status":"publish","type":"docs","link":"https:\/\/modulus.help\/kb\/docs\/documentation\/personnel-apis-v1\/api-list-employees\/","title":{"rendered":"API: List Employees"},"content":{"rendered":"

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.<\/p>\n

Request<\/h4>\n\n\n\n\n\n\n\n\n\n\n\n
Property<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
API Name<\/td>\nEmployee<\/td>\n<\/tr>\n
URL<\/td>\nhttps:\/\/your_account.modulus.biz\/api\/hr\/v1\/Employee<\/td>\n<\/tr>\n
Method<\/td>\nGET<\/td>\n<\/tr>\n
Source<\/td>\nThird Party Server<\/td>\n<\/tr>\n
Recipient<\/td>\nmodulus\u00ae Server<\/td>\n<\/tr>\n
Accept<\/td>\napplication\/json<\/td>\n<\/tr>\n
Authentication<\/td>\nBearer token<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Request Headers<\/h4>\n\n\n\n\n\n\n
Header<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Authorization<\/td>\nYes<\/td>\nBearer token for authentication. Format: Bearer <token><\/td>\n<\/tr>\n
Accept<\/td>\nYes<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Query String Parameters<\/h4>\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Parameter<\/th>\nRequired<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
employee_code<\/td>\nNo<\/td>\nString<\/td>\nFilter by employee code.<\/td>\n<\/tr>\n
employment_status<\/td>\nNo<\/td>\nString<\/td>\nFilter by employment status. Possible values: Working, Terminated, Resigned.<\/td>\n<\/tr>\n
location_id<\/td>\nNo<\/td>\nInteger<\/td>\nFilter by location ID.<\/td>\n<\/tr>\n
position_id<\/td>\nNo<\/td>\nInteger<\/td>\nFilter by position ID.<\/td>\n<\/tr>\n
department_id<\/td>\nNo<\/td>\nInteger<\/td>\nFilter by department ID.<\/td>\n<\/tr>\n
direct_head_code<\/td>\nNo<\/td>\nString<\/td>\nFilter employees reporting directly to the specified employee code.<\/td>\n<\/tr>\n
groups<\/td>\nNo<\/td>\nString<\/td>\nComma-separated information groups: personal_info, employment_info. Omit to return root fields only.<\/td>\n<\/tr>\n
page_number<\/td>\nNo<\/td>\nInteger<\/td>\nPage number. Default = 1.<\/td>\n<\/tr>\n
page_size<\/td>\nNo<\/td>\nInteger<\/td>\nRecords per page. Default = 50; recommended maximum = 500.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

When multiple employee filters are supplied, they are combined using AND logic. Employee codes are strings; preserve leading zeros.<\/p>\n

Information Groups<\/h4>\n\n\n\n\n\n\n
Group<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
personal_info<\/td>\nGender, date of birth, nationality, religion, marital status, military status, and education.<\/td>\n<\/tr>\n
employment_info<\/td>\nEmployment status, join date, layoff date, location, position, department, contract type, working days, working hours, attendance scheme, and direct head code.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Example: groups=personal_info,employment_info. Unrequested groups are omitted completely, rather than returned as null.<\/p>\n

Responses<\/h4>\n\n\n\n\n\n\n\n
HTTP Status<\/th>\nresult<\/th>\ntitle<\/th>\nmessage<\/th>\nobject<\/th>\n<\/tr>\n<\/thead>\n
200 OK<\/td>\ntrue<\/td>\nSuccess<\/td>\nEmployees listed successfully.<\/td>\n\n
{\n  \"meta_data\": {\n    \"page_count\": 3,\n    \"page_number\": 1,\n    \"page_size\": 50,\n    \"record_count\": 127\n  },\n  \"data\": [\n    {\n      \"employee_code\": \"0001\",\n      \"full_name\": \"Ahmed Mohamed Hassan\",\n      \"short_name\": \"Ahmed Hassan\",\n      \"personal_info\": {\n        \"gender\": \"Male\",\n        \"date_of_birth\": \"1990-05-15\",\n        \"nationality\": \"Egyptian\",\n        \"religion\": \"Muslim\",\n        \"marital_status\": \"Married\",\n        \"military_status\": \"Completed\",\n        \"education\": \"Bachelor of Commerce\"\n      },\n      \"employment_info\": {\n        \"employment_status\": \"Working\",\n        \"join_date\": \"2020-01-15\",\n        \"layoff_date\": null,\n        \"location\": {\n          \"id\": 3,\n          \"name\": \"Cairo HQ\"\n        },\n        \"position\": {\n          \"id\": 17,\n          \"name\": \"Senior Accountant\"\n        },\n        \"department\": {\n          \"id\": 12,\n          \"name\": \"Finance\"\n        },\n        \"contract_type\": {\n          \"id\": 1,\n          \"name\": \"Full Time\"\n        },\n        \"working_days\": 5,\n        \"working_hours\": 40,\n        \"attendance_scheme\": {\n          \"id\": 4,\n          \"name\": \"Standard Office Hours\"\n        },\n        \"direct_head_code\": \"0025\"\n      }\n    }\n  ]\n}<\/pre>\n<\/td>\n<\/tr>\n
200 OK (No Matches)<\/td>\ntrue<\/td>\nSuccess<\/td>\nNo employees found matching your conditions.<\/td>\n\n
{\n  \"meta_data\": {\n    \"page_count\": 0,\n    \"page_number\": 1,\n    \"page_size\": 50,\n    \"record_count\": 0\n  },\n  \"data\": []\n}<\/pre>\n<\/td>\n<\/tr>\n
400 Bad Request<\/td>\nfalse<\/td>\nInvalid Request<\/td>\nInvalid information group: payroll_info.<\/td>\n\n
null<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Response Structure<\/h4>\n\n\n\n\n\n\n\n\n
Field<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
result<\/td>\nBoolean<\/td>\nIndicates whether the request was processed successfully.<\/td>\n<\/tr>\n
title<\/td>\nString<\/td>\nShort response title.<\/td>\n<\/tr>\n
message<\/td>\nString<\/td>\nHuman-readable response message.<\/td>\n<\/tr>\n
object<\/td>\nObject \/ null<\/td>\nResponse payload containing meta_data and data for successful list requests.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Pagination Metadata<\/h4>\n\n\n\n\n\n\n\n\n
Field<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
page_count<\/td>\nInteger<\/td>\nTotal number of pages.<\/td>\n<\/tr>\n
page_number<\/td>\nInteger<\/td>\nCurrent page number.<\/td>\n<\/tr>\n
page_size<\/td>\nInteger<\/td>\nRequested records per page.<\/td>\n<\/tr>\n
record_count<\/td>\nInteger<\/td>\nTotal records matching supplied filters.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Root Employee Fields<\/h4>\n\n\n\n\n\n\n\n
Field<\/th>\nType<\/th>\nNullable<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
employee_code<\/td>\nString<\/td>\nNo<\/td>\nEmployee code. Always returned. Preserve leading zeros.<\/td>\n<\/tr>\n
full_name<\/td>\nString<\/td>\nNo<\/td>\nEmployee full name. Always returned.<\/td>\n<\/tr>\n
short_name<\/td>\nString<\/td>\nYes<\/td>\nEmployee short\/display name. Always returned.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Personal Information Fields<\/h4>\n\n\n\n\n\n\n\n\n\n\n\n
Field<\/th>\nType<\/th>\nNullable<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
gender<\/td>\nString<\/td>\nYes<\/td>\nEmployee gender.<\/td>\n<\/tr>\n
date_of_birth<\/td>\nDate<\/td>\nYes<\/td>\nDate of birth in YYYY-MM-DD format.<\/td>\n<\/tr>\n
nationality<\/td>\nString<\/td>\nYes<\/td>\nEmployee nationality.<\/td>\n<\/tr>\n
religion<\/td>\nString<\/td>\nYes<\/td>\nEmployee religion.<\/td>\n<\/tr>\n
marital_status<\/td>\nString<\/td>\nYes<\/td>\nEmployee marital status.<\/td>\n<\/tr>\n
military_status<\/td>\nString<\/td>\nYes<\/td>\nEmployee military service status.<\/td>\n<\/tr>\n
education<\/td>\nString<\/td>\nYes<\/td>\nEmployee education information.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Employment Information Fields<\/h4>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Field<\/th>\nType<\/th>\nNullable<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
employment_status<\/td>\nString<\/td>\nNo<\/td>\nCurrent employment status.<\/td>\n<\/tr>\n
join_date<\/td>\nDate<\/td>\nYes<\/td>\nJoin date in YYYY-MM-DD format.<\/td>\n<\/tr>\n
layoff_date<\/td>\nDate<\/td>\nYes<\/td>\nLayoff\/termination date in YYYY-MM-DD format.<\/td>\n<\/tr>\n
location<\/td>\nObject<\/td>\nYes<\/td>\nAssigned location as {id, name}.<\/td>\n<\/tr>\n
position<\/td>\nObject<\/td>\nYes<\/td>\nAssigned position as {id, name}.<\/td>\n<\/tr>\n
department<\/td>\nObject<\/td>\nYes<\/td>\nAssigned department as {id, name}.<\/td>\n<\/tr>\n
contract_type<\/td>\nObject<\/td>\nYes<\/td>\nAssigned contract type as {id, name}.<\/td>\n<\/tr>\n
working_days<\/td>\nNumber<\/td>\nYes<\/td>\nConfigured working days.<\/td>\n<\/tr>\n
working_hours<\/td>\nNumber<\/td>\nYes<\/td>\nConfigured working hours.<\/td>\n<\/tr>\n
attendance_scheme<\/td>\nObject<\/td>\nYes<\/td>\nAttendance scheme as {id, name}.<\/td>\n<\/tr>\n
direct_head_code<\/td>\nString<\/td>\nYes<\/td>\nEmployee code of direct head\/supervisor.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Reference Objects<\/h4>\n
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.<\/p>\n
{\n  \"id\": 12,\n  \"name\": \"Finance\"\n}<\/pre>\n
Example 1 – Root Information Only<\/h4>\n\n\n\n\n
Request<\/th>\n\n
curl --request GET 'https:\/\/your_account.modulus.biz\/api\/hr\/v1\/Employee?page_number=1&page_size=50' \\\n--header 'Accept: application\/json' \\\n--header 'Authorization: Bearer <token>'<\/pre>\n<\/td>\n<\/tr>\n
200 OK<\/th>\n\n
{\n  \"result\": true,\n  \"title\": \"Success\",\n  \"message\": \"Employees listed successfully.\",\n  \"object\": {\n    \"meta_data\": {\n      \"page_count\": 1,\n      \"page_number\": 1,\n      \"page_size\": 50,\n      \"record_count\": 1\n    },\n    \"data\": [\n      {\n        \"employee_code\": \"0001\",\n        \"full_name\": \"Ahmed Mohamed Hassan\",\n        \"short_name\": \"Ahmed Hassan\"\n      }\n    ]\n  }\n}<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Example 2 – Personal and Employment Information<\/h4>\n\n\n\n\n
Request<\/th>\n\n
curl --request GET 'https:\/\/your_account.modulus.biz\/api\/hr\/v1\/Employee?groups=personal_info,employment_info&page_number=1&page_size=50' \\\n--header 'Accept: application\/json' \\\n--header 'Authorization: Bearer <token>'<\/pre>\n<\/td>\n<\/tr>\n
200 OK<\/th>\n\n
{\n  \"result\": true,\n  \"title\": \"Success\",\n  \"message\": \"Employees listed successfully.\",\n  \"object\": {\n    \"meta_data\": {\n      \"page_count\": 3,\n      \"page_number\": 1,\n      \"page_size\": 50,\n      \"record_count\": 127\n    },\n    \"data\": [\n      {\n        \"employee_code\": \"0001\",\n        \"full_name\": \"Ahmed Mohamed Hassan\",\n        \"short_name\": \"Ahmed Hassan\",\n        \"personal_info\": {\n          \"gender\": \"Male\",\n          \"date_of_birth\": \"1990-05-15\",\n          \"nationality\": \"Egyptian\",\n          \"religion\": \"Muslim\",\n          \"marital_status\": \"Married\",\n          \"military_status\": \"Completed\",\n          \"education\": \"Bachelor of Commerce\"\n        },\n        \"employment_info\": {\n          \"employment_status\": \"Working\",\n          \"join_date\": \"2020-01-15\",\n          \"layoff_date\": null,\n          \"location\": {\n            \"id\": 3,\n            \"name\": \"Cairo HQ\"\n          },\n          \"position\": {\n            \"id\": 17,\n            \"name\": \"Senior Accountant\"\n          },\n          \"department\": {\n            \"id\": 12,\n            \"name\": \"Finance\"\n          },\n          \"contract_type\": {\n            \"id\": 1,\n            \"name\": \"Full Time\"\n          },\n          \"working_days\": 5,\n          \"working_hours\": 40,\n          \"attendance_scheme\": {\n            \"id\": 4,\n            \"name\": \"Standard Office Hours\"\n          },\n          \"direct_head_code\": \"0025\"\n        }\n      }\n    ]\n  }\n}<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Example 3 – Filtered Employee List<\/h4>\n\n\n\n
Request<\/th>\n\n
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' \\\n--header 'Accept: application\/json' \\\n--header 'Authorization: Bearer <token>'<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Example 4 – Specific Employee<\/h4>\n\n\n\n
Request<\/th>\n\n
curl --request GET 'https:\/\/your_account.modulus.biz\/api\/hr\/v1\/Employee?employee_code=0001&groups=personal_info,employment_info' \\\n--header 'Accept: application\/json' \\\n--header 'Authorization: Bearer <token>'<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Example 5 – No Matching Employees<\/h4>\n\n\n\n\n
Request<\/th>\n\n
curl --request GET 'https:\/\/your_account.modulus.biz\/api\/hr\/v1\/Employee?employee_code=NONEXISTENT' \\\n--header 'Accept: application\/json' \\\n--header 'Authorization: Bearer <token>'<\/pre>\n<\/td>\n<\/tr>\n
200 OK<\/th>\n\n
{\n  \"result\": true,\n  \"title\": \"Success\",\n  \"message\": \"No employees found matching your conditions.\",\n  \"object\": {\n    \"meta_data\": {\n      \"page_count\": 0,\n      \"page_number\": 1,\n      \"page_size\": 50,\n      \"record_count\": 0\n    },\n    \"data\": []\n  }\n}<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Example 6 – Invalid Group<\/h4>\n\n\n\n\n
Request<\/th>\n\n
curl --request GET 'https:\/\/your_account.modulus.biz\/api\/hr\/v1\/Employee?groups=personal_info,payroll_info' \\\n--header 'Accept: application\/json' \\\n--header 'Authorization: Bearer <token>'<\/pre>\n<\/td>\n<\/tr>\n
400 Bad Request<\/th>\n\n
{\n  \"result\": false,\n  \"title\": \"Invalid Request\",\n  \"message\": \"Invalid information group: payroll_info.\",\n  \"object\": null\n}<\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Integration Notes<\/h4>\n
    \n
  • Use employee_code and direct_head_code as strings to preserve leading zeros.<\/li>\n
  • Use location_id, position_id, and department_id to filter organizational assignments.<\/li>\n
  • Contract type is returned in employment_info but is not currently exposed as a request filter.<\/li>\n
  • When groups is omitted, only employee_code, full_name, and short_name are returned.<\/li>\n
  • Requested groups are expanded for each employee; unrequested groups are omitted.<\/li>\n
  • Use pagination metadata instead of assuming a response contains the full result set.<\/li>\n<\/ul>\n","protected":false},"featured_media":0,"parent":3773,"menu_order":3,"comment_status":"closed","ping_status":"closed","template":"","doc_tag":[],"comment_count":0,"_links":{"self":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4778"}],"collection":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/types\/docs"}],"replies":[{"embeddable":true,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/comments?post=4778"}],"version-history":[{"count":8,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4778\/revisions"}],"predecessor-version":[{"id":4801,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4778\/revisions\/4801"}],"up":[{"embeddable":true,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/3773"}],"next":[{"title":"API: List Employee Schedules","link":"https:\/\/modulus.help\/kb\/docs\/documentation\/personnel-apis-v1\/api-list-employee-schedules\/","href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4558"}],"prev":[{"title":"API: List Attendance Logs","link":"https:\/\/modulus.help\/kb\/docs\/documentation\/personnel-apis-v1\/api-list-attendance-logs\/","href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4771"}],"wp:attachment":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/media?parent=4778"}],"wp:term":[{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/doc_tag?post=4778"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}