Employees

Employees are the core entities in the Personnel Management module, representing every individual on record across the organization. Each employee record holds personal information, government identification numbers, address details, and links to their assigned position, organization, and timekeeping policy.

Access to this module requires the Super Admin, HR Admin, or HR Timekeeping role.

The employee model

The employee model contains all the information about an individual employee, including their personal details, government IDs, physical description, address, and links to related HR records.

Properties

Name
id
Type
string
Description
Unique UUID identifier for the employee.
Name
initials
Type
string
Description
Computed initials derived from the employee's name.
Name
user
Type
object | null
Description
The linked user account, present when loaded. Contains: id, is_super_user, name, initials, avatar_thumbnail, avatar_url, email, username, roles, two_factor_enabled, disabled_at, last_login_at, created_at, updated_at.
Name
avatar_thumbnail
Type
string | null
Description
URL to a thumbnail-sized version of the employee's avatar image.
Name
avatar_url
Type
string | null
Description
URL to the employee's full-size avatar image.
Name
user_id
Type
integer | null
Description
The ID of the linked user account, if any. Optional.
Name
biometric_id
Type
string | null
Description
Identifier used by the biometric device integration. Optional.
Name
position_id
Type
string | null
Description
UUID of the employee's assigned position. Optional.
Name
organization_id
Type
string | null
Description
UUID of the employee's assigned organization. Optional.
Name
timekeeping_policy_id
Type
string | null
Description
UUID of the employee's assigned timekeeping policy. Optional.
Name
timekeeping_policy
Type
object | null
Description
The assigned timekeeping policy, present when loaded. Contains: id, name.
Name
employee_number
Type
string | null
Description
The employee's official employee number. Optional.
Name
full_name
Type
string
Description
Computed full name combining first, middle, last name, and suffix.
Name
first_name
Type
string
Description
The employee's first name.
Name
last_name
Type
string
Description
The employee's last name.
Name
middle_name
Type
string | null
Description
The employee's middle name. Optional.
Name
suffix
Type
string | null
Description
Name suffix (e.g., Jr., Sr., III). Optional.
Name
sex
Type
string
Description
The employee's sex.
Name
birthdate
Type
date
Description
The employee's date of birth.
Name
birthplace
Type
string | null
Description
The employee's place of birth. Optional.
Name
age
Type
integer
Description
Computed age derived from the employee's birthdate.
Name
civil_status
Type
string
Description
The employee's civil status.
Name
citizenship
Type
string | null
Description
The employee's citizenship. Optional.
Name
nationality
Type
string | null
Description
The employee's nationality. Optional.
Name
religion
Type
string | null
Description
The employee's religion. Optional.
Name
preferred_name
Type
string | null
Description
The employee's preferred first name. Optional.
Name
preferred_middle_initials
Type
string | null
Description
The employee's preferred middle initials. Optional.
Name
sss_number
Type
string | null
Description
Social Security System (SSS) number. Optional.
Name
tin_number
Type
string | null
Description
Tax Identification Number (TIN). Optional.
Name
philhealth_number
Type
string | null
Description
PhilHealth identification number. Optional.
Name
gsis_number
Type
string | null
Description
Government Service Insurance System (GSIS) number. Optional.
Name
gsis_policy_number
Type
string | null
Description
GSIS policy number. Optional.
Name
pagibig_number
Type
string | null
Description
Pag-IBIG Fund membership number. Optional.
Name
prc_number
Type
string | null
Description
Professional Regulation Commission (PRC) license number. Optional.
Name
agency_employee_number
Type
string | null
Description
Employee number assigned by the agency. Optional.
Name
height
Type
integer | null
Description
The employee's height, in centimeters. Optional.
Name
weight
Type
integer | null
Description
The employee's weight, in kilograms. Optional.
Name
blood_type
Type
string | null
Description
The employee's blood type. Optional.
Name
built
Type
string | null
Description
The employee's build/body type. Optional.
Name
complexion
Type
string | null
Description
The employee's complexion. Optional.
Name
distinguishing_marks
Type
string | null
Description
Notable distinguishing marks (e.g., scars, tattoos, moles). Optional.
Name
hair_color
Type
string | null
Description
The employee's hair color. Optional.
Name
eye_color
Type
string | null
Description
The employee's eye color. Optional.
Name
shoes_size
Type
integer | null
Description
The employee's shoe size. Optional.
Name
head_size
Type
integer | null
Description
The employee's head size. Optional.
Name
ethnic_group
Type
string | null
Description
The employee's ethnic group. Optional.
Name
permanent_address_1
Type
string | null
Description
Permanent address, line 1. Optional.
Name
permanent_address_2
Type
string | null
Description
Permanent address, line 2. Optional.
Name
permanent_province
Type
string | null
Description
Permanent address province. Optional.
Name
permanent_city
Type
string | null
Description
Permanent address city/municipality. Optional.
Name
permanent_zipcode
Type
string | null
Description
Permanent address zip code. Optional.
Name
permanent_barangay
Type
string | null
Description
Permanent address barangay. Optional.
Name
current_address_1
Type
string | null
Description
Current address, line 1. Optional.
Name
current_address_2
Type
string | null
Description
Current address, line 2. Optional.
Name
current_province
Type
string | null
Description
Current address province. Optional.
Name
current_city
Type
string | null
Description
Current address city/municipality. Optional.
Name
current_zipcode
Type
string | null
Description
Current address zip code. Optional.
Name
current_barangay
Type
string | null
Description
Current address barangay. Optional.
Name
full_address
Type
string | null
Description
Computed full address string, assembled from the current address fields.
Name
email
Type
string | null
Description
The employee's personal or work email address. Optional.
Name
home_number
Type
string | null
Description
The employee's home phone number. Optional.
Name
work_number
Type
string | null
Description
The employee's work phone number. Optional.
Name
is_pwd
Type
boolean
Description
Whether the employee is a Person with Disability (PWD).
Name
is_military
Type
boolean
Description
Whether the employee has a military background.
Name
rank
Type
string | null
Description
The employee's military rank. Applies when is_military is true. Optional.
Name
designation
Type
string | null
Description
The employee's designation. Optional.
Name
settings
Type
object | null
Description
The employee's settings, present when loaded.
Name
biometric_setting
Type
object | null
Description
The employee's biometric device settings, present when loaded.
Name
employment_type
Type
object | null
Description
The employee's employment type, present when loaded.
Name
position
Type
object | null
Description
The employee's assigned position, present when loaded. Nested Position resource.
Name
organization
Type
object | null
Description
The employee's assigned organization, present when loaded. Nested Organization resource.
Name
created_at
Type
timestamp
Description
Timestamp when the employee record was created.
Name
updated_at
Type
timestamp
Description
Timestamp when the employee record was last updated.

GET/pms/employees

List all employees

This endpoint allows you to retrieve a paginated list of all employees. By default, a maximum of 50 employees are shown per page.

Optional attributes

Name
filter[payroll_roster_id]
Type
string
Description
Scope employees to those included in the given payroll roster.
Name
filter[payroll_run_id]
Type
string
Description
Scope employees to those included in the given payroll run.
Name
filter[organization_slug]
Type
string
Description
Scope employees to those belonging to the given organization, identified by slug.
Name
filter[employment_type]
Type
string
Description
Filter employees by an exact match on employment type.
Name
filter[user_id]
Type
integer
Description
Filter employees by an exact match on the linked user ID.
Name
filter[search]
Type
string
Description
Search employees by first name or last name.
Name
except[employee_id][]
Type
array
Description
Exclude specific employee IDs from the results. Useful for exclusion lists in UI pickers.
Name
per_page
Type
integer
Description
Number of employees to return per page (default: 50).
Name
page
Type
integer
Description
Page number for pagination (default: 1).

Request

GET

/pms/employees

curl https://your-domain.com/api/pms/employees \
  -H "Accept: application/json" \
  --cookie "mainframe_session=your-session-cookie"

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "initials": "JD",
      "avatar_thumbnail": null,
      "avatar_url": null,
      "user_id": 12,
      "biometric_id": "BIO-00123",
      "position_id": "b2c3d4e5-f6a7-8901-bcde-f21345678901",
      "organization_id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
      "timekeeping_policy_id": "d4e5f6a7-b8c9-0123-defa-bc4567890123",
      "employee_number": "EMP-2024-0456",
      "full_name": "Juan Santos Dela Cruz",
      "first_name": "Juan",
      "last_name": "Dela Cruz",
      "middle_name": "Santos",
      "suffix": null,
      "sex": "male",
      "birthdate": "1990-06-15",
      "age": 36,
      "civil_status": "married",
      "employment_type": {
        "id": "e5f6a7b8-c9d0-1234-efab-cd5678901234",
        "name": "Regular"
      },
      "designation": "Senior Accountant",
      "is_pwd": false,
      "is_military": false,
      "created_at": "2024-01-10T10:00:00+00:00",
      "updated_at": "2025-03-15T09:00:00+00:00"
    }
  ],
  "links": {
    "first": "https://your-domain.com/api/pms/employees?page=1",
    "last": "https://your-domain.com/api/pms/employees?page=8",
    "prev": null,
    "next": "https://your-domain.com/api/pms/employees?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 8,
    "per_page": 50,
    "to": 50,
    "total": 384
  }
}

POST/pms/employees

Create an employee

This endpoint allows you to create a new employee record in the system.

Required attributes

Name
first_name
Type
string
Description
The employee's first name.
Name
last_name
Type
string
Description
The employee's last name.
Name
birthdate
Type
date
Description
The employee's date of birth.
Name
sex
Type
string
Description
The employee's sex.
Name
civil_status
Type
string
Description
The employee's civil status.

Optional attributes

Name
middle_name
Type
string
Description
The employee's middle name.
Name
suffix
Type
string
Description
Name suffix (e.g., Jr., Sr., III).
Name
complexion
Type
string
Description
The employee's complexion.
Name
blood_type
Type
string
Description
The employee's blood type.
Name
height
Type
integer
Description
The employee's height, in centimeters.
Name
weight
Type
integer
Description
The employee's weight, in kilograms.
Name
head_size
Type
integer
Description
The employee's head size.
Name
shoes_size
Type
integer
Description
The employee's shoe size.
Name
avatar
Type
string
Description
Base64-encoded avatar image. Maximum size of approximately 2MB.
Name
sss_number
Type
string
Description
Social Security System (SSS) number.
Name
tin_number
Type
string
Description
Tax Identification Number (TIN).
Name
philhealth_number
Type
string
Description
PhilHealth identification number.
Name
gsis_number
Type
string
Description
Government Service Insurance System (GSIS) number.
Name
gsis_policy_number
Type
string
Description
GSIS policy number.
Name
pagibig_number
Type
string
Description
Pag-IBIG Fund membership number.
Name
prc_number
Type
string
Description
Professional Regulation Commission (PRC) license number.
Name
agency_employee_number
Type
string
Description
Employee number assigned by the agency.
Name
permanent_address_1
Type
string
Description
Permanent address, line 1.
Name
permanent_address_2
Type
string
Description
Permanent address, line 2.
Name
permanent_province
Type
string
Description
Permanent address province.
Name
permanent_city
Type
string
Description
Permanent address city/municipality.
Name
permanent_zipcode
Type
string
Description
Permanent address zip code.
Name
permanent_barangay
Type
string
Description
Permanent address barangay.
Name
current_address_1
Type
string
Description
Current address, line 1.
Name
current_address_2
Type
string
Description
Current address, line 2.
Name
current_province
Type
string
Description
Current address province.
Name
current_city
Type
string
Description
Current address city/municipality.
Name
current_zipcode
Type
string
Description
Current address zip code.
Name
current_barangay
Type
string
Description
Current address barangay.
Name
email
Type
string
Description
The employee's personal or work email address.
Name
home_number
Type
string
Description
The employee's home phone number.
Name
work_number
Type
string
Description
The employee's work phone number.
Name
is_pwd
Type
boolean
Description
Whether the employee is a Person with Disability (PWD).
Name
is_military
Type
boolean
Description
Whether the employee has a military background.

Request

POST

/pms/employees

curl -X POST https://your-domain.com/api/pms/employees \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie" \
  -d '{
    "first_name": "Maria",
    "middle_name": "Reyes",
    "last_name": "Santos",
    "suffix": null,
    "birthdate": "1992-03-22",
    "sex": "female",
    "civil_status": "single",
    "sss_number": "34-1234567-8",
    "tin_number": "123-456-789-000",
    "philhealth_number": "12-345678901-2",
    "pagibig_number": "1234-5678-9012",
    "permanent_address_1": "123 Rizal Street",
    "permanent_province": "Metro Manila",
    "permanent_city": "Quezon City",
    "permanent_zipcode": "1100",
    "permanent_barangay": "Bagong Pag-asa",
    "current_address_1": "123 Rizal Street",
    "current_province": "Metro Manila",
    "current_city": "Quezon City",
    "current_zipcode": "1100",
    "current_barangay": "Bagong Pag-asa",
    "email": "maria.santos@example.com",
    "work_number": "0281234567",
    "is_pwd": false,
    "is_military": false
  }'

Response

{
  "data": {
    "id": "f6a7b8c9-d0e1-2345-fabc-de6789012345",
    "initials": "MS",
    "avatar_thumbnail": null,
    "avatar_url": null,
    "user_id": null,
    "biometric_id": null,
    "position_id": null,
    "organization_id": null,
    "timekeeping_policy_id": null,
    "employee_number": null,
    "full_name": "Maria Reyes Santos",
    "first_name": "Maria",
    "last_name": "Santos",
    "middle_name": "Reyes",
    "suffix": null,
    "sex": "female",
    "birthdate": "1992-03-22",
    "age": 34,
    "civil_status": "single",
    "sss_number": "34-1234567-8",
    "tin_number": "123-456-789-000",
    "philhealth_number": "12-345678901-2",
    "pagibig_number": "1234-5678-9012",
    "permanent_address_1": "123 Rizal Street",
    "permanent_province": "Metro Manila",
    "permanent_city": "Quezon City",
    "permanent_zipcode": "1100",
    "permanent_barangay": "Bagong Pag-asa",
    "current_address_1": "123 Rizal Street",
    "current_province": "Metro Manila",
    "current_city": "Quezon City",
    "current_zipcode": "1100",
    "current_barangay": "Bagong Pag-asa",
    "full_address": "123 Rizal Street, Bagong Pag-asa, Quezon City, Metro Manila, 1100",
    "email": "maria.santos@example.com",
    "work_number": "0281234567",
    "is_pwd": false,
    "is_military": false,
    "created_at": "2026-07-24T10:30:00+00:00",
    "updated_at": "2026-07-24T10:30:00+00:00"
  }
}

GET/pms/employees/{id}

Get an employee

This endpoint allows you to retrieve a single employee by ID.

Path parameters

Name
id
Type
string
Description
The UUID of the employee to retrieve.

Request

GET

/pms/employees/{id}

curl https://your-domain.com/api/pms/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Accept: application/json" \
  --cookie "mainframe_session=your-session-cookie"

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "initials": "JD",
    "avatar_thumbnail": null,
    "avatar_url": null,
    "user_id": 12,
    "biometric_id": "BIO-00123",
    "position_id": "b2c3d4e5-f6a7-8901-bcde-f21345678901",
    "organization_id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
    "timekeeping_policy_id": "d4e5f6a7-b8c9-0123-defa-bc4567890123",
    "employee_number": "EMP-2024-0456",
    "full_name": "Juan Santos Dela Cruz",
    "first_name": "Juan",
    "last_name": "Dela Cruz",
    "middle_name": "Santos",
    "suffix": null,
    "sex": "male",
    "birthdate": "1990-06-15",
    "age": 36,
    "civil_status": "married",
    "sss_number": "33-7654321-0",
    "tin_number": "987-654-321-000",
    "philhealth_number": "21-098765432-1",
    "pagibig_number": "9876-5432-1098",
    "permanent_address_1": "456 Bonifacio Avenue",
    "permanent_province": "Metro Manila",
    "permanent_city": "Manila",
    "permanent_zipcode": "1000",
    "permanent_barangay": "San Antonio",
    "current_address_1": "456 Bonifacio Avenue",
    "current_province": "Metro Manila",
    "current_city": "Manila",
    "current_zipcode": "1000",
    "current_barangay": "San Antonio",
    "full_address": "456 Bonifacio Avenue, San Antonio, Manila, Metro Manila, 1000",
    "email": "juan.delacruz@example.com",
    "work_number": "0289876543",
    "is_pwd": false,
    "is_military": false,
    "designation": "Senior Accountant",
    "created_at": "2024-01-10T10:00:00+00:00",
    "updated_at": "2025-03-15T09:00:00+00:00"
  }
}

PUT/pms/employees/{id}

Update an employee

This endpoint allows you to update an existing employee's information.

Path parameters

Name
id
Type
string
Description
The UUID of the employee to update.

Required attributes

Name
first_name
Type
string
Description
The employee's first name.
Name
last_name
Type
string
Description
The employee's last name.
Name
birthdate
Type
date
Description
The employee's date of birth.
Name
sex
Type
string
Description
The employee's sex.
Name
civil_status
Type
string
Description
The employee's civil status.

Optional attributes

All optional attributes from the create endpoint are also accepted here: middle_name, suffix, complexion, blood_type, height, weight, head_size, shoes_size, avatar, government IDs (sss_number, tin_number, philhealth_number, gsis_number, gsis_policy_number, pagibig_number, prc_number, agency_employee_number), address fields (permanent and current), contact fields (email, home_number, work_number), and is_pwd/is_military.

Request

PUT

/pms/employees/{id}

curl -X PUT https://your-domain.com/api/pms/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie" \
  -d '{
    "first_name": "Juan",
    "middle_name": "Santos",
    "last_name": "Dela Cruz",
    "birthdate": "1990-06-15",
    "sex": "male",
    "civil_status": "married",
    "email": "juan.delacruz@example.com",
    "work_number": "0289876500",
    "current_address_1": "789 Mabini Street",
    "current_province": "Metro Manila",
    "current_city": "Makati",
    "current_zipcode": "1200",
    "current_barangay": "Poblacion"
  }'

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "initials": "JD",
    "full_name": "Juan Santos Dela Cruz",
    "first_name": "Juan",
    "last_name": "Dela Cruz",
    "middle_name": "Santos",
    "sex": "male",
    "birthdate": "1990-06-15",
    "age": 36,
    "civil_status": "married",
    "current_address_1": "789 Mabini Street",
    "current_province": "Metro Manila",
    "current_city": "Makati",
    "current_zipcode": "1200",
    "current_barangay": "Poblacion",
    "full_address": "789 Mabini Street, Poblacion, Makati, Metro Manila, 1200",
    "email": "juan.delacruz@example.com",
    "work_number": "0289876500",
    "updated_at": "2026-07-24T11:15:00+00:00"
  }
}

DELETE/pms/employees/{id}

Delete an employee

This endpoint allows you to delete an employee record.

Path parameters

Name
id
Type
string
Description
The UUID of the employee to delete.

Request

DELETE

/pms/employees/{id}

curl -X DELETE https://your-domain.com/api/pms/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie"

Response

HTTP/1.1 204 No Content

Other employee actions

A few additional endpoints support related employee actions:

DELETE /api/pms/employees/{employee}/avatar_delete — remove the employee's avatar image.
PATCH /api/pms/employees/{employee}/update-timekeeping-policy — change the employee's assigned timekeeping policy.