Employees API

17 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

GET/api/v1/employees

Employee directory

Directory fields are visible to every member. Work pass state only to readers of all work passes.

Access

Permission directory:read

Parameters

Name	In	Type	Required
page	query	integer	no
pageSize	query	integer	no
sort	query	enum	no
q	query	string	no
departmentId	query	string (uuid)	no
teamId	query	string (uuid)	no
locationId	query	string (uuid)	no
costCentreId	query	string (uuid)	no
managerId	query	string (uuid)	no
status	query	string	no
scope	query	enum	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstringrequired
  • employeeNumberstringrequired
  • namestringrequired
  • legalNamestringrequired
  • preferredNamestring | nullrequired
  • jobTitlestring | nullrequired
  • departmentobject or nullrequired

    • idstringrequired
    • namestringrequired
  • teamobject or nullrequired

    • idstringrequired
    • namestringrequired
  • locationobject or nullrequired

    • idstringrequired
    • namestringrequired
  • managerobject or nullrequired

    • idstringrequired
    • namestringrequired
  • workEmailstring | nullrequired
  • statusobjectrequired

    • codeenumrequired

      one of "not_started", "active", "leaving", "former", "no_tenure"

    • labelstringrequired
    • sincestring
    • lastWorkingDaystring
  • workPassStateenum or nullrequired

    one of "valid", "expiring", "expired", "cancelled"

  • hireDatestring | nullrequired
• pageintegerrequired

  min -9007199254740991

• pageSizeintegerrequired

  min -9007199254740991

• totalintegerrequired

  min -9007199254740991

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

POST/api/v1/employees

Hire an employee

Creates the employee, tenure, employment record, optional compensation (payroll roles only), onboarding checklist and sign-in invitation.

Access

Permission employment:create

Request body

application/json, object, required

• personobjectrequired

  • employeeNumberstring or null

    max length 20

  • legalNamestringrequired

    min length 1 · max length 200

  • preferredNamestring or null

    max length 100

  • idTypeenumrequired

    one of "nric", "fin", "other"

  • idNumberstringrequired

    min length 1

  • dobstringrequired
  • genderenum or null

    one of "female", "male", "other", "undisclosed"

  • nationalitystring or null

    max length 60

  • residencyStatusenumrequired

    one of "citizen", "pr", "foreigner"

  • prStartDatestring | null
  • sprCpfOptionenum or null

    one of "gg", "fg", "ff"

  • sprCpfOptionApprovedOnstring | null
  • racestring or null

    max length 60

  • raceSecondarystring or null

    max length 60

  • religionenum or null

    one of "buddhism", "christianity", "islam", "hinduism", "taoism", "sikhism", "other", "none", "undisclosed"

  • shgOptOutOnstring | null
  • workEmailstring (email) or null
  • personalEmailstring (email) or null
  • mobilestring or null

    max length 30

  • addressobject or null

    • blockstring or null

      max length 20

    • streetstring or null

      max length 200

    • unitstring or null

      max length 20

    • buildingstring or null

      max length 200

    • postalCodestring or null

      max length 10

    • countrystring or null

      min length 2 · max length 2

• jobobjectrequired

  • jobTitlestringrequired

    min length 1 · max length 120

  • departmentIdstring (uuid)required
  • teamIdstring (uuid) or null
  • locationIdstring (uuid) or null
  • costCentreIdstring (uuid) or null
  • managerEmployeeIdstring (uuid) or null
  • employmentTypeenumrequired

    one of "full_time", "part_time", "contract", "intern"

  • workScheduleIdstring (uuid) or null
  • probationEndstring | null
  • eaCoveredboolean
  • isWorkmanboolean
  • isManagerOrExecutiveboolean
  • hireDatestringrequired
• compensationobject or null

  • payBasisenumrequired

    one of "monthly", "hourly"

  • amountCentsintegerrequired

    min 0

  • reasonstring or null

    max length 200

• allowancesarray of object

  • allowanceTypeIdstring (uuid)required
  • amountCentsintegerrequired

    min 0

• workPassobject or null

  • passTypeenumrequired

    one of "EP", "S_PASS", "WP", "DP_LOC", "LTVP_LOC", "PEP", "ONE", "TEP", "OTHER"

  • passNumberstring or null

    max length 30

  • issuedOnstring | null
  • expiresOnstringrequired
  • notesstring or null

    max length 500

• emergencyContactsarray of object

  • namestringrequired

    min length 1 · max length 120

  • relationshipstringrequired

    min length 1 · max length 60

  • phonestringrequired

    min length 1

• inviteboolean

Responses

201 Success. object

• employeeIdstringrequired
• inviteobject or nullrequired

  • statusenumrequired

    one of "emailed", "link", "linked", "skipped"

  • inviteUrlstring | nullrequired
  • messagestringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 409 conflict, duplicate_id_number, reporting_cycle

GET/api/v1/employees/{id}

Get an employee

Sections the caller may not read are omitted and listed in redactedFields.

Access

Permission directory:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstringrequired
• employeeNumberstringrequired
• namestringrequired
• legalNamestringrequired
• preferredNamestring | nullrequired
• workEmailstring | nullrequired
• statusobjectrequired

  • codeenumrequired

    one of "not_started", "active", "leaving", "former", "no_tenure"

  • labelstringrequired
  • sincestring
  • lastWorkingDaystring
• jobobject or nullrequired

  • effectiveFromstringrequired

    YYYY-MM-DD

  • jobTitlestringrequired
  • departmentobject or nullrequired

    • idstringrequired
    • namestringrequired
  • teamobject or nullrequired

    • idstringrequired
    • namestringrequired
  • locationobject or nullrequired

    • idstringrequired
    • namestringrequired
  • managerobject or nullrequired

    • idstringrequired
    • namestringrequired
• employmentobject

  • costCentreobject or nullrequired

    • idstringrequired
    • namestringrequired
  • employmentTypestringrequired
  • workScheduleobject or nullrequired

    • idstringrequired
    • namestringrequired
  • probationEndstring | nullrequired
  • eaCoveredbooleanrequired
  • isWorkmanbooleanrequired
  • isManagerOrExecutivebooleanrequired
  • tenuresarray of objectrequired

    • idstringrequired
    • hireDatestringrequired

      YYYY-MM-DD

    • lastWorkingDaystring | nullrequired
    • cessationReasonstring | nullrequired
    • noticeDaysnumber | nullrequired
  • historyarray of objectrequired

    • idstringrequired
    • effectiveFromstringrequired

      YYYY-MM-DD

    • effectiveTostring | nullrequired
    • jobTitlestringrequired
    • departmentstring | nullrequired
    • teamstring | nullrequired
    • locationstring | nullrequired
    • managerstring | nullrequired
    • employmentTypestringrequired
    • eventIdstringrequired
  • eventsarray of objectrequired

    • idstringrequired
    • typestringrequired
    • effectiveDatestringrequired

      YYYY-MM-DD

    • statusenumrequired

      one of "scheduled", "effective", "cancelled"

    • payloadobjectrequired
    • createdAtstringrequired
  • directReportsarray of objectrequired

    • idstringrequired
    • namestringrequired
• personalobject

  • idTypestringrequired
  • idNumberMaskedstringrequiredsensitive: nric
  • dobstringrequired

    YYYY-MM-DD

  • ageintegerrequired

    min -9007199254740991

  • genderstring | nullrequired
  • nationalitystring | nullrequired
  • residencyStatusstringrequired
  • prStartDatestring | nullrequired
  • sprCpfOptionstring | nullrequired
  • sprCpfOptionApprovedOnstring | nullrequired
  • racestring | nullrequired
  • raceSecondarystring | nullrequired
  • religionstring | nullrequired
  • shgOptOutOnstring | nullrequired
  • personalEmailstring | nullrequired
  • mobilestring | nullrequired
  • addressobject or nullrequired

    • blockstring | null
    • streetstring | null
    • unitstring | null
    • buildingstring | null
    • postalCodestring | null
    • countrystring | null
• emergencyContactsarray of object

  • idstringrequired
  • namestringrequired
  • relationshipstringrequired
  • phonestringrequired
• workPassesarray of object

  • idstringrequired
  • passTypestringrequired
  • passTypeLabelstringrequired
  • passNumberMaskedstring | nullrequiredsensitive: nric
  • issuedOnstring | nullrequired
  • expiresOnstringrequired

    YYYY-MM-DD

  • cancelledOnstring | nullrequired
  • notesstring | nullrequired
  • stateenumrequired

    one of "valid", "expiring", "expired", "cancelled"

• compensationobject

  • currentobject or nullrequired

    • idstringrequired
    • effectiveFromstringrequired

      YYYY-MM-DD

    • effectiveTostring | nullrequired
    • payBasisenumrequired

      one of "monthly", "hourly"

    • amountCentsintegerrequiredsensitive: salary

      min -9007199254740991

    • reasonstring | nullrequired
    • retroactivebooleanrequired
    • eventIdstringrequired
  • historyarray of objectrequired

    • idstringrequired
    • effectiveFromstringrequired

      YYYY-MM-DD

    • effectiveTostring | nullrequired
    • payBasisenumrequired

      one of "monthly", "hourly"

    • amountCentsintegerrequiredsensitive: salary

      min -9007199254740991

    • reasonstring | nullrequired
    • retroactivebooleanrequired
    • eventIdstringrequired
  • allowancesarray of objectrequired

    • idstringrequired
    • allowanceTypeIdstringrequired
    • namestringrequired
    • amountCentsintegerrequiredsensitive: salary

      min -9007199254740991

    • effectiveFromstringrequired

      YYYY-MM-DD

    • effectiveTostring | nullrequired
• bankobject

  • currentobject or nullrequired

    • idstringrequired
    • bankCodestringrequired
    • bankNamestringrequired
    • accountLast4stringrequiredsensitive: bank
    • holderNamestringrequiredsensitive: bank
    • effectiveFromstringrequired

      YYYY-MM-DD

    • effectiveTostring | nullrequired
  • historyarray of objectrequired

    • idstringrequired
    • bankCodestringrequired
    • bankNamestringrequired
    • accountLast4stringrequiredsensitive: bank
    • holderNamestringrequiredsensitive: bank
    • effectiveFromstringrequired

      YYYY-MM-DD

    • effectiveTostring | nullrequired
• redactedFieldsarray of stringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

PATCH/api/v1/employees/{id}

Update personal and identity details (HR)

Access

Permission personal_details:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• legalNamestring

  min length 1 · max length 200

• preferredNamestring or null

  max length 100

• idTypeenum

  one of "nric", "fin", "other"

• idNumberstring

  min length 1

• dobstring
• genderenum or null

  one of "female", "male", "other", "undisclosed"

• nationalitystring or null

  max length 60

• residencyStatusenum

  one of "citizen", "pr", "foreigner"

• prStartDatestring | null
• sprCpfOptionenum or null

  one of "gg", "fg", "ff"

• sprCpfOptionApprovedOnstring | null
• racestring or null

  max length 60

• raceSecondarystring or null

  max length 60

• religionenum or null

  one of "buddhism", "christianity", "islam", "hinduism", "taoism", "sikhism", "other", "none", "undisclosed"

• shgOptOutOnstring | null
• workEmailstring (email) or null
• personalEmailstring (email) or null
• mobilestring or null

  max length 30

• addressobject or null

  • blockstring or null

    max length 20

  • streetstring or null

    max length 200

  • unitstring or null

    max length 20

  • buildingstring or null

    max length 200

  • postalCodestring or null

    max length 10

  • countrystring or null

    min length 2 · max length 2

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict, duplicate_id_number

POST/api/v1/employees/{id}/bank-accounts

Set the bank account from a date (previous one kept as history)

Access

Permission bank_details:update

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• bankCodeenumrequired

  one of "DBSSSGSG", "POSBSGSG", "OCBCSGSG", "UOVBSGSG", "SCBLSGSG", "HSBCSGS2", "CITISGSL", "MBBESGS2", "BKCHSGSG", "ICBKSGSG", "RHBBSGSG", "CIBBSGSG", "HLBBSGSG", "SIVBSGSG", "TRWISGSG", "GXSPSGSG"

• accountNumberstringrequired

  min length 1

• holderNamestringrequired

  min length 1 · max length 140

• effectiveFromstringrequired

Responses

201 Success. object

• idstringrequired
• accountMaskedstringrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, reauth_required, self_change_requires_approval
• 404 not_found

POST/api/v1/employees/{id}/bank/reveal

Reveal the full current bank account number once (re-authentication, 30 per hour, audited)

Access

Permission bank_details:read

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• valuestringrequiredsensitive: bank

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, reauth_required
• 404 not_found
• 429 rate_limited

GET/api/v1/employees/{id}/checklists

Onboarding and offboarding checklists

Access

Permission employment:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• itemsarray of objectrequired

  • idstringrequired
  • kindenumrequired

    one of "onboarding", "offboarding"

  • statusenumrequired

    one of "open", "cancelled"

  • anchorDatestringrequired

    YYYY-MM-DD

  • itemsarray of objectrequired

    • idstringrequired
    • titlestringrequired
    • assigneeRoleenumrequired

      one of "hr_admin", "payroll_admin", "manager", "employee"

    • dueOnstringrequired

      YYYY-MM-DD

    • statusenumrequired

      one of "open", "done", "skipped", "cancelled"

    • skipReasonstring | nullrequired
    • doneAtstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

GET/api/v1/employees/{id}/compensation

Compensation history

Access

Permission compensation:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• currentobject or nullrequired

  • idstringrequired
  • effectiveFromstringrequired

    YYYY-MM-DD

  • effectiveTostring | nullrequired
  • payBasisenumrequired

    one of "monthly", "hourly"

  • amountCentsintegerrequiredsensitive: salary

    min -9007199254740991

  • reasonstring | nullrequired
  • retroactivebooleanrequired
  • eventIdstringrequired
• historyarray of objectrequired

  • idstringrequired
  • effectiveFromstringrequired

    YYYY-MM-DD

  • effectiveTostring | nullrequired
  • payBasisenumrequired

    one of "monthly", "hourly"

  • amountCentsintegerrequiredsensitive: salary

    min -9007199254740991

  • reasonstring | nullrequired
  • retroactivebooleanrequired
  • eventIdstringrequired
• allowancesarray of objectrequired

  • idstringrequired
  • allowanceTypeIdstringrequired
  • namestringrequired
  • amountCentsintegerrequired

    min -9007199254740991

  • effectiveFromstringrequired
  • effectiveTostring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required
• 404 not_found

PUT/api/v1/employees/{id}/emergency-contacts

Replace emergency contacts (at most 3)

Access

Permission emergency_contacts:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• contactsarray of objectrequired

  • namestringrequired

    min length 1 · max length 120

  • relationshipstringrequired

    min length 1 · max length 60

  • phonestringrequired

    min length 1

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

POST/api/v1/employees/{id}/events

Record a lifecycle event

transfer, promotion, salary_change, probation_confirmed, resignation, termination or rehire. Future-dated events are scheduled.

Access

Permission employment:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object | object | object | object | object | object, required

Responses

201 Success. object

• eventIdstringrequired
• statusenumrequired

  one of "scheduled", "effective", "cancelled"

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, self_change_requires_approval
• 404 not_found
• 409 conflict, reporting_cycle

POST/api/v1/employees/{id}/events/{eventId}/cancel

Cancel a scheduled lifecycle event

Access

Permission employment:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes
eventId	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 conflict

POST/api/v1/employees/{id}/nric/reveal

Reveal the full NRIC/FIN once (re-authentication, 30 per hour, audited)

Access

Permission personal_details:read

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• valuestringrequiredsensitive: nric

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required, reauth_required
• 404 not_found
• 429 rate_limited

POST/api/v1/employees/{id}/work-passes

Add a work pass

Access

Permission work_pass:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• passTypeenumrequired

  one of "EP", "S_PASS", "WP", "DP_LOC", "LTVP_LOC", "PEP", "ONE", "TEP", "OTHER"

• passNumberstring or null

  max length 30

• issuedOnstring | null
• expiresOnstringrequired
• notesstring or null

  max length 500

Responses

201 Success. object

• idstringrequired
• passTypestringrequired
• passTypeLabelstringrequired
• passNumberMaskedstring | nullrequiredsensitive: nric
• issuedOnstring | nullrequired
• expiresOnstringrequired

  YYYY-MM-DD

• cancelledOnstring | nullrequired
• notesstring | nullrequired
• stateenumrequired

  one of "valid", "expiring", "expired", "cancelled"

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

PATCH/api/v1/employees/{id}/work-passes/{passId}

Update or cancel a work pass

Access

Permission work_pass:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes
passId	path	string (uuid)	yes

Request body

application/json, object, required

• passTypeenum

  one of "EP", "S_PASS", "WP", "DP_LOC", "LTVP_LOC", "PEP", "ONE", "TEP", "OTHER"

• passNumberstring or null

  max length 30

• issuedOnstring | null
• expiresOnstring
• notesstring or null

  max length 500

• cancelledOnstring | null

Responses

200 Success. object

• idstringrequired
• passTypestringrequired
• passTypeLabelstringrequired
• passNumberMaskedstring | nullrequiredsensitive: nric
• issuedOnstring | nullrequired
• expiresOnstringrequired

  YYYY-MM-DD

• cancelledOnstring | nullrequired
• notesstring | nullrequired
• stateenumrequired

  one of "valid", "expiring", "expired", "cancelled"

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

GET/api/v1/employees/export

Export the employee list (CSV or XLSX, masked identifiers)

Access

Permission directory:read

Parameters

Name	In	Type	Required
format	query	enum	no
columns	query	string	no
q	query	string	no
departmentId	query	string (uuid)	no
teamId	query	string (uuid)	no
locationId	query	string (uuid)	no
costCentreId	query	string (uuid)	no
managerId	query	string (uuid)	no
status	query	string	no
scope	query	enum	no

Responses

200 CSV or XLSX file text/csv

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/employees/export/columns

Columns the caller may export

Access

Permission directory:read

Responses

200 Success. object

• itemsarray of objectrequired

  • keystringrequired
  • labelstringrequired
  • unmaskedbooleanrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/employees/export/unmasked

Export with unmasked NRIC/FIN or bank numbers (requires recent sign-in)

Access

Permission personal_details:read

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
format	query	enum	no
columns	query	string	no
q	query	string	no
departmentId	query	string (uuid)	no
teamId	query	string (uuid)	no
locationId	query	string (uuid)	no
costCentreId	query	string (uuid)	no
managerId	query	string (uuid)	no
status	query	string	no
scope	query	enum	no

Responses

200 CSV or XLSX file text/csv

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required, reauth_required