People API

11 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.

POST/api/v1/people/checklist-items/{itemId}

Complete, skip (with reason) or reopen a checklist item

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
itemId	path	string (uuid)	yes

Request body

application/json, object | object | object, required

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

GET/api/v1/people/imports/{jobId}

Get an import preview

Access

Permission employment:read

Parameters

Name	In	Type	Required
jobId	path	string (uuid)	yes

Responses

200 Success. object

• jobIdstringrequired
• kindenumrequired

  one of "employees", "compensation", "ytd"

• fileNamestring | nullrequired
• statusenumrequired

  one of "previewed", "committed", "failed"

• totalRowsintegerrequired

  min -9007199254740991

• validRowsintegerrequired

  min -9007199254740991

• errorsarray of objectrequired

  • rowintegerrequired

    min -9007199254740991

  • columnstringrequired
  • valuestringrequired
  • messagestringrequired
• rowsarray of objectrequired

  • rowintegerrequired

    min -9007199254740991

  • summarystringrequired
  • validbooleanrequired
• expiresAtstringrequired
• canCommitbooleanrequired

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

POST/api/v1/people/imports/{jobId}/commit

Confirm an import: all rows in one transaction, or none

Access

Permission employment:read

Parameters

Name	In	Type	Required
jobId	path	string (uuid)	yes

Responses

200 Success. object

• jobIdstringrequired
• kindenumrequired

  one of "employees", "compensation", "ytd"

• fileNamestring | nullrequired
• statusenumrequired

  one of "previewed", "committed", "failed"

• totalRowsintegerrequired

  min -9007199254740991

• validRowsintegerrequired

  min -9007199254740991

• errorsarray of objectrequired

  • rowintegerrequired

    min -9007199254740991

  • columnstringrequired
  • valuestringrequired
  • messagestringrequired
• rowsarray of objectrequired

  • rowintegerrequired

    min -9007199254740991

  • summarystringrequired
  • validbooleanrequired
• expiresAtstringrequired
• canCommitbooleanrequired

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

POST/api/v1/people/imports/{kind}/preview

Upload a CSV and preview the import (nothing is written)

Access

Permission employment:read

Parameters

Name	In	Type	Required
kind	path	enum	yes

Request body

application/json, object, required

• fileNamestring or null

  max length 200

• contentstringrequired

  max length 5243904

Responses

201 Success. object

• jobIdstringrequired
• kindenumrequired

  one of "employees", "compensation", "ytd"

• fileNamestring | nullrequired
• statusenumrequired

  one of "previewed", "committed", "failed"

• totalRowsintegerrequired

  min -9007199254740991

• validRowsintegerrequired

  min -9007199254740991

• errorsarray of objectrequired

  • rowintegerrequired

    min -9007199254740991

  • columnstringrequired
  • valuestringrequired
  • messagestringrequired
• rowsarray of objectrequired

  • rowintegerrequired

    min -9007199254740991

  • summarystringrequired
  • validbooleanrequired
• expiresAtstringrequired
• canCommitbooleanrequired

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

GET/api/v1/people/imports/templates/{kind}

Download an import template (CSV)

Access

Permission employment:read

Parameters

Name	In	Type	Required
kind	path	enum	yes

Responses

200 CSV template text/csv

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

GET/api/v1/people/inbox

People work assigned to me: open checklist items and change requests to decide

Access

Any signed-in member (own data only)

Responses

200 Success. object

• checklistItemsarray of objectrequired

  • itemIdstringrequired
  • employeeIdstringrequired
  • titlestringrequired
  • dueOnstringrequired
  • kindenumrequired

    one of "onboarding", "offboarding"

• changeRequestsarray of objectrequired

  • idstringrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "cancelled"

  • routeToRoleenumrequired

    one of "hr_admin", "payroll_admin"

  • fieldNamesarray of stringrequired
  • proposedobjectrequired
  • submittedAtstringrequired
  • decidedAtstring | nullrequired
  • effectiveFromstring | nullrequired
  • decisionNotestring | nullrequired
  • employeeIdstringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

POST/api/v1/people/me/change-requests

Request a change to sensitive details (legal name, ID, DOB, residency, race, religion, bank)

Access

Any signed-in member (own data only)

Request body

application/json, object, required

• personalobject

  • legalNamestring

    min length 1 · max length 200

  • idTypeenum

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

  • idNumberstring

    min length 1

  • dobstring
  • residencyStatusenum

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

  • prStartDatestring | 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"

• bankobject

  • 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

• attachmentFileKeystring or null

  max length 512

• notestring or null

  max length 500

Responses

201 Success. object

• itemsarray of objectrequired

  • idstringrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "cancelled"

  • routeToRoleenumrequired

    one of "hr_admin", "payroll_admin"

  • fieldNamesarray of stringrequired
  • proposedobjectrequired
  • submittedAtstringrequired
  • decidedAtstring | nullrequired
  • effectiveFromstring | nullrequired
  • decisionNotestring | nullrequired

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

POST/api/v1/people/me/change-requests/{requestId}/cancel

Withdraw my pending change request

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
requestId	path	string (uuid)	yes

Responses

204 No content.

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

GET/api/v1/people/me/profile

My profile, with my pending change requests

Access

Any signed-in member (own data only)

Responses

200 Success. object

• employeeobjectrequired

  • 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
• changeRequestsarray of objectrequired

  • idstringrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "cancelled"

  • routeToRoleenumrequired

    one of "hr_admin", "payroll_admin"

  • fieldNamesarray of stringrequired
  • proposedobjectrequired
  • submittedAtstringrequired
  • decidedAtstring | nullrequired
  • effectiveFromstring | nullrequired
  • decisionNotestring | nullrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required
• 404 not_found

PATCH/api/v1/people/me/profile

Edit my preferred name, personal email, mobile, address and emergency contacts

Access

Any signed-in member (own data only)

Request body

application/json, object, required

• preferredNamestring or null

  max length 100

• 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

• emergencyContactsarray of object

  • 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, mfa_enrolment_required
• 404 not_found

GET/api/v1/people/reference

Reference lists for people forms (banks, pass types, races, religions)

Access

Any signed-in member (own data only)

Responses

200 Success. object

• banksarray of objectrequired

  • codestringrequired
  • namestringrequired
• workPassTypesarray of objectrequired

  • codestringrequired
  • labelstringrequired
• racesarray of stringrequired
• religionsarray of stringrequired
• gendersarray of stringrequired
• employmentTypesarray of stringrequired
• terminationReasonsarray of stringrequired
• exportColumnsarray of objectrequired

  • keystringrequired
  • labelstringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required