Leave API

30 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/leave/adjustments

Adjust an employee's balance (positive or negative, with a reason; audited)

Access

Permission leave:update

Request body

application/json, object, required

• employeeIdstring (uuid)required
• leaveTypeIdstring (uuid)required
• yearintegerrequired

  min 2000 · max 2100

• amountnumberrequired
• childIdstring (uuid) or null
• reasonstringrequired

  min length 3 · max length 300

Responses

201 Success. object

• idstring (uuid)required
• quantitynumberrequired
• unitenumrequired

  one of "days", "hours"

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

GET/api/v1/leave/balances

Leave balances for an employee and year (default: your own, this year)

Access

Permission leave:read

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	no
year	query	integer	no

Responses

200 Success. object

• itemsarray of objectrequired

  • typeIdstring (uuid)required
  • codestringrequired
  • namestringrequired
  • statutoryCodestring | nullrequired
  • unitenumrequired

    one of "days", "hours"

  • trackedbooleanrequired
  • eligiblebooleanrequired
  • eligibleFromstring | nullrequired
  • yearnumberrequired
  • childIdstring (uuid) or nullrequired
  • entitlementnumberrequired
  • carriedForwardnumberrequired
  • expirednumberrequired
  • adjustmentsnumberrequired
  • takennumberrequired
  • pendingnumberrequired
  • availablenumber | nullrequired
  • carryExpiresOnstring | nullrequired
  • explanationarray of stringrequired

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

GET/api/v1/leave/calendar

Who is on leave (types shown only where you may see them)

Access

Permission leave:read

Parameters

Name	In	Type	Required
from	query	string	yes
to	query	string	yes
view	query	enum	no

Responses

200 Success. object

• fromstringrequired
• tostringrequired
• holidaysarray of objectrequired

  • datestringrequired
  • namestringrequired
• peoplearray of objectrequired

  • employeeIdstring (uuid)required
  • namestringrequired
  • selfbooleanrequired
  • entriesarray of objectrequired

    • datestringrequired
    • sessionenumrequired

      one of "full", "am", "pm"

    • statusenumrequired

      one of "approved", "pending"

    • labelstringrequired
    • typeCodestring | nullrequired
    • requestIdstring (uuid) or nullrequired

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

GET/api/v1/leave/children

An employee's children (for parental and childcare leave)

Access

Permission leave:read

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • employeeIdstring (uuid)required
  • namestringrequired
  • birthDatestring | nullrequired
  • expectedDeliveryDatestring | nullrequired
  • isCitizenbooleanrequired
  • birthOrdernumberrequired
  • stillbornbooleanrequired
  • adoptionIntentDatestring | nullrequired
  • marriedToMotherboolean | nullrequired

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

POST/api/v1/leave/children

Add a child (yours, or an employee's as owner or HR admin)

Access

Permission leave:create

Request body

application/json, object, required

• employeeIdstring (uuid)
• namestringrequired

  min length 1 · max length 80

• birthDatestring | null
• expectedDeliveryDatestring | null
• isCitizenbooleanrequired
• birthOrderintegerrequired

  min 1 · max 20

• stillbornboolean

  default false

• adoptionIntentDatestring | null
• marriedToMotherboolean | null

Responses

201 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• namestringrequired
• birthDatestring | nullrequired
• expectedDeliveryDatestring | nullrequired
• isCitizenbooleanrequired
• birthOrdernumberrequired
• stillbornbooleanrequired
• adoptionIntentDatestring | nullrequired
• marriedToMotherboolean | nullrequired

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

PUT/api/v1/leave/children/{id}

Update a child's details

Access

Permission leave:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• employeeIdstring (uuid)
• namestringrequired

  min length 1 · max length 80

• birthDatestring | null
• expectedDeliveryDatestring | null
• isCitizenbooleanrequired
• birthOrderintegerrequired

  min 1 · max 20

• stillbornboolean

  default false

• adoptionIntentDatestring | null
• marriedToMotherboolean | null

Responses

200 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• namestringrequired
• birthDatestring | nullrequired
• expectedDeliveryDatestring | nullrequired
• isCitizenbooleanrequired
• birthOrdernumberrequired
• stillbornbooleanrequired
• adoptionIntentDatestring | nullrequired
• marriedToMotherboolean | nullrequired

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

GET/api/v1/leave/encashments

List your encashment requests, or an employee's as HR

Access

Permission leave:read

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • employeeIdstring (uuid)required
  • leaveTypeIdstring (uuid)required
  • leaveYearnumberrequired
  • unitenumrequired

    one of "days", "hours"

  • quantitynumberrequired
  • amountCentsintegerrequired

    min -9007199254740991

  • rateTextstringrequired
  • rateDatestringrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "withdrawn", "reserved", "paid"

  • approvalRequestIdstring (uuid) or nullrequired
  • payrollRunIdstring (uuid) or nullrequired
• candidatesarray of objectrequired

  • ledgerEntryIdstring (uuid)required
  • leaveTypeIdstring (uuid)required
  • leaveYearnumberrequired
  • unitenumrequired

    one of "days", "hours"

  • quantitynumberrequired

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

POST/api/v1/leave/encashments

Request leave encashment for approval under the leave policy

Access

Permission leave:create

Request body

application/json, object, required

• employeeIdstring (uuid)
• leaveTypeIdstring (uuid)required
• daysnumberrequired

  max 365

• ledgerEntryIdstring (uuid)
• workingDaysPerWeeknumber

  min 0.5 · max 7

Responses

201 Success. object

• idstring (uuid)required
• employeeIdstring (uuid)required
• leaveTypeIdstring (uuid)required
• leaveYearnumberrequired
• unitenumrequired

  one of "days", "hours"

• quantitynumberrequired
• amountCentsintegerrequired

  min -9007199254740991

• rateTextstringrequired
• rateDatestringrequired
• statusenumrequired

  one of "pending", "approved", "rejected", "withdrawn", "reserved", "paid"

• approvalRequestIdstring (uuid) or nullrequired
• payrollRunIdstring (uuid) or nullrequired

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

POST/api/v1/leave/encashments/{id}/withdraw

Withdraw pending encashment and release its leave balance

Access

Permission leave:create

Parameters

Name	In	Type	Required
id	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

GET/api/v1/leave/holidays

Singapore public holidays and the organisation's extra holidays for a year

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
year	query	integer	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid) or nullrequired
  • datestringrequired
  • namestringrequired
  • sourceenumrequired

    one of "gazetted", "organisation"

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

POST/api/v1/leave/holidays

Add an extra public holiday (such as Polling Day)

Access

Permission policies:update

Request body

application/json, object, required

• datestringrequired
• namestringrequired

  min length 1 · max length 80

Responses

201 Success. object

• idstring (uuid) or nullrequired
• datestringrequired
• namestringrequired
• sourceenumrequired

  one of "gazetted", "organisation"

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

DELETE/api/v1/leave/holidays/{id}

Remove an extra holiday

Access

Permission policies:update

Parameters

Name	In	Type	Required
id	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

GET/api/v1/leave/payroll-input

Approved unpaid leave per employee and date for a pay period (payroll pro-ration)

Access

Permission payroll:read

Parameters

Name	In	Type	Required
periodStart	query	string	yes
periodEnd	query	string	yes

Responses

200 Success. object

• itemsarray of objectrequired

  • sourceIdstring (uuid)required
  • requestIdstring (uuid)required
  • employeeIdstring (uuid)required
  • datestringrequired
  • daysnumberrequired
  • leaveTypeCodestringrequired
  • leaveTypeNamestringrequired

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

GET/api/v1/leave/policies

Leave types with their policies (Settings → Leave policies)

Access

Permission policies:read

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
  • statutoryCodestring | nullrequired
  • paidbooleanrequired
  • halfDaysbooleanrequired
  • attachmentenumrequired

    one of "none", "optional", "required"

  • attachmentLabelstring | nullrequired
  • sensitivebooleanrequired
  • needsChildbooleanrequired
  • perChildbooleanrequired
  • unlimitedbooleanrequired
  • archivedbooleanrequired
  • encashablebooleanrequired
  • employeeEncashmentRequestsbooleanrequired
  • kindenumrequired

    one of "statutory", "company"

  • dayCountingenumrequired

    one of "working_days", "working_days_including_holidays"

  • policyobjectrequired

    • entitlementobject | object | object | objectrequired
    • minServiceMonthsintegerrequired

      min 0 · max 24

    • proratebooleanrequired
    • accrualenumrequired

      one of "upfront", "monthly"

    • carryForwardobject or nullrequired

      • maxDaysnumber or nullrequired

        min 0 · max 365

      • expiresAfterMonthsinteger or nullrequired

        min 1 · max 36

    • encashablebooleanrequired
    • employeeEncashmentRequestsboolean
  • sortOrdernumberrequired

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

POST/api/v1/leave/policies

Add a company leave type (birthday, marriage, volunteering…)

Access

Permission policies:update

Request body

application/json, object, required

• codestringrequired
• namestringrequired

  min length 1 · max length 60

• paidboolean

  default true

• halfDaysboolean

  default true

• attachmentenum

  one of "none", "optional", "required" · default "none"

• attachmentLabelstring or null

  max length 80

• sensitiveboolean

  default false

• policyobjectrequired

  • entitlementobject | object | object | objectrequired
  • minServiceMonthsintegerrequired

    min 0 · max 24

  • proratebooleanrequired
  • accrualenumrequired

    one of "upfront", "monthly"

  • carryForwardobject or nullrequired

    • maxDaysnumber or nullrequired

      min 0 · max 365

    • expiresAfterMonthsinteger or nullrequired

      min 1 · max 36

  • encashablebooleanrequired
  • employeeEncashmentRequestsboolean

Responses

201 Success. object

• idstring (uuid)required
• codestringrequired
• namestringrequired
• statutoryCodestring | nullrequired
• paidbooleanrequired
• halfDaysbooleanrequired
• attachmentenumrequired

  one of "none", "optional", "required"

• attachmentLabelstring | nullrequired
• sensitivebooleanrequired
• needsChildbooleanrequired
• perChildbooleanrequired
• unlimitedbooleanrequired
• archivedbooleanrequired
• encashablebooleanrequired
• employeeEncashmentRequestsbooleanrequired
• kindenumrequired

  one of "statutory", "company"

• dayCountingenumrequired

  one of "working_days", "working_days_including_holidays"

• policyobjectrequired

  • entitlementobject | object | object | objectrequired
  • minServiceMonthsintegerrequired

    min 0 · max 24

  • proratebooleanrequired
  • accrualenumrequired

    one of "upfront", "monthly"

  • carryForwardobject or nullrequired

    • maxDaysnumber or nullrequired

      min 0 · max 365

    • expiresAfterMonthsinteger or nullrequired

      min 1 · max 36

  • encashablebooleanrequired
  • employeeEncashmentRequestsboolean
• sortOrdernumberrequired

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

PATCH/api/v1/leave/policies/{id}

Update a leave type's policy (never below the statutory minimum)

Access

Permission policies:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• namestring

  min length 1 · max length 60

• halfDaysboolean
• attachmentenum

  one of "none", "optional", "required"

• attachmentLabelstring or null

  max length 80

• sensitiveboolean
• paidboolean
• policyobject

  • entitlementobject | object | object | objectrequired
  • minServiceMonthsintegerrequired

    min 0 · max 24

  • proratebooleanrequired
  • accrualenumrequired

    one of "upfront", "monthly"

  • carryForwardobject or nullrequired

    • maxDaysnumber or nullrequired

      min 0 · max 365

    • expiresAfterMonthsinteger or nullrequired

      min 1 · max 36

  • encashablebooleanrequired
  • employeeEncashmentRequestsboolean

Responses

200 Success. object

• idstring (uuid)required
• codestringrequired
• namestringrequired
• statutoryCodestring | nullrequired
• paidbooleanrequired
• halfDaysbooleanrequired
• attachmentenumrequired

  one of "none", "optional", "required"

• attachmentLabelstring | nullrequired
• sensitivebooleanrequired
• needsChildbooleanrequired
• perChildbooleanrequired
• unlimitedbooleanrequired
• archivedbooleanrequired
• encashablebooleanrequired
• employeeEncashmentRequestsbooleanrequired
• kindenumrequired

  one of "statutory", "company"

• dayCountingenumrequired

  one of "working_days", "working_days_including_holidays"

• policyobjectrequired

  • entitlementobject | object | object | objectrequired
  • minServiceMonthsintegerrequired

    min 0 · max 24

  • proratebooleanrequired
  • accrualenumrequired

    one of "upfront", "monthly"

  • carryForwardobject or nullrequired

    • maxDaysnumber or nullrequired

      min 0 · max 365

    • expiresAfterMonthsinteger or nullrequired

      min 1 · max 36

  • encashablebooleanrequired
  • employeeEncashmentRequestsboolean
• sortOrdernumberrequired

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

POST/api/v1/leave/policies/{id}/archive

Archive or restore a company leave type

Access

Permission policies:update

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• archivedbooleanrequired

Responses

200 Success. object

• idstring (uuid)required
• codestringrequired
• namestringrequired
• statutoryCodestring | nullrequired
• paidbooleanrequired
• halfDaysbooleanrequired
• attachmentenumrequired

  one of "none", "optional", "required"

• attachmentLabelstring | nullrequired
• sensitivebooleanrequired
• needsChildbooleanrequired
• perChildbooleanrequired
• unlimitedbooleanrequired
• archivedbooleanrequired
• encashablebooleanrequired
• employeeEncashmentRequestsbooleanrequired
• kindenumrequired

  one of "statutory", "company"

• dayCountingenumrequired

  one of "working_days", "working_days_including_holidays"

• policyobjectrequired

  • entitlementobject | object | object | objectrequired
  • minServiceMonthsintegerrequired

    min 0 · max 24

  • proratebooleanrequired
  • accrualenumrequired

    one of "upfront", "monthly"

  • carryForwardobject or nullrequired

    • maxDaysnumber or nullrequired

      min 0 · max 365

    • expiresAfterMonthsinteger or nullrequired

      min 1 · max 36

  • encashablebooleanrequired
  • employeeEncashmentRequestsboolean
• sortOrdernumberrequired

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

POST/api/v1/leave/quote

Work out an application without submitting it (days counted, balance before and after)

Access

Permission leave:create

Request body

application/json, object, required

• employeeIdstring (uuid)
• leaveTypeIdstring (uuid)required
• startDatestringrequired
• endDatestringrequired
• startSessionenum

  one of "full", "am", "pm" · default "full"

• endSessionenum

  one of "full", "am", "pm" · default "full"

• childIdstring (uuid) or null

Responses

200 Success. object

• employeeIdstring (uuid)required
• typeobjectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
  • statutoryCodestring | nullrequired
  • paidbooleanrequired
  • halfDaysbooleanrequired
  • attachmentenumrequired

    one of "none", "optional", "required"

  • attachmentLabelstring | nullrequired
  • sensitivebooleanrequired
  • needsChildbooleanrequired
  • perChildbooleanrequired
  • unlimitedbooleanrequired
  • archivedbooleanrequired
  • encashablebooleanrequired
  • employeeEncashmentRequestsbooleanrequired
• unitenumrequired

  one of "days", "hours"

• quantitynumberrequired
• daysarray of objectrequired

  • datestringrequired
  • sessionenumrequired

    one of "full", "am", "pm"

  • quantitynumberrequired
  • notestring | nullrequired
• yearsarray of objectrequired

  • yearnumberrequired
  • quantitynumberrequired
  • trackedbooleanrequired
  • availablenumber | nullrequired
  • afternumber | nullrequired
• issuesarray of objectrequired

  • codestringrequired
  • pathstringrequired
  • messagestringrequired
• warningsarray of stringrequired
• okbooleanrequired

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

GET/api/v1/leave/reports/government-paid

Government-paid leave days to claim on the MSF portal (and NS make-up pay)

Access

Permission leave_claims:read

Parameters

Name	In	Type	Required
from	query	string	yes
to	query	string	yes

Responses

200 Success. object

• itemsarray of objectrequired

  • requestIdstring (uuid)required
  • employeeIdstring (uuid)required
  • employeeNamestringrequired
  • leaveTypestringrequired
  • schemestringrequired
  • childstring | nullrequired
  • startDatestringrequired
  • endDatestringrequired
  • daysnumberrequired
  • employerDaysnumberrequired
  • governmentDaysnumberrequired
  • unpaidDaysnumberrequired
  • claimBystring | nullrequired
  • claimViastringrequired

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

GET/api/v1/leave/reports/government-paid.csv

Government-paid leave days as CSV

Access

Permission leave_claims:read

Parameters

Name	In	Type	Required
from	query	string	yes
to	query	string	yes

Responses

200 CSV file text/csv

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

GET/api/v1/leave/requests

List leave requests you can see (yours; your team's; everyone's for admins)

Access

Permission leave:read

Parameters

Name	In	Type	Required
employeeId	query	string (uuid)	no
status	query	string	no
from	query	string	no
to	query	string	no
limit	query	integer	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • employeeobjectrequired

    • idstring (uuid)required
    • namestringrequired
  • typeobjectrequired

    • idstring (uuid)required
    • codestringrequired
    • namestringrequired
  • startDatestringrequired
  • endDatestringrequired
  • startSessionenumrequired

    one of "full", "am", "pm"

  • endSessionenumrequired

    one of "full", "am", "pm"

  • unitenumrequired

    one of "days", "hours"

  • quantitynumberrequired
  • reasonstring | nullrequired
  • statusenumrequired

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

  • childobject or nullrequired

    • idstring (uuid)required
    • namestringrequired
  • attachmentsarray of objectrequired

    • idstring (uuid)required
    • filenamestringrequired
    • contentTypestringrequired
    • sizeBytesnumberrequired
  • approvalRequestIdstring (uuid) or nullrequired
  • cancellationRequestIdstring (uuid) or nullrequired
  • onBehalfbooleanrequired
  • cancelReasonstring | nullrequired
  • createdAtstringrequired
  • decidedAtstring | nullrequired
  • daysarray of object

    • datestringrequired
    • sessionenumrequired

      one of "full", "am", "pm"

    • quantitynumberrequired

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

POST/api/v1/leave/requests

Apply for leave (your own, or on behalf of an employee as owner or HR admin)

Access

Permission leave:create

Request body

application/json, object, required

• employeeIdstring (uuid)
• leaveTypeIdstring (uuid)required
• startDatestringrequired
• endDatestringrequired
• startSessionenum

  one of "full", "am", "pm" · default "full"

• endSessionenum

  one of "full", "am", "pm" · default "full"

• childIdstring (uuid) or null
• reasonstring or null

  max length 500

• attachmentsarray of object

  • filenamestringrequired

    min length 1 · max length 120

  • contentTypeenumrequired

    one of "application/pdf", "image/jpeg", "image/png", "image/webp", "image/heic"

  • dataBase64stringrequired

    min length 1 · max length 6990571

Responses

201 Success. object

• idstring (uuid)required
• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• typeobjectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
• startDatestringrequired
• endDatestringrequired
• startSessionenumrequired

  one of "full", "am", "pm"

• endSessionenumrequired

  one of "full", "am", "pm"

• unitenumrequired

  one of "days", "hours"

• quantitynumberrequired
• reasonstring | nullrequired
• statusenumrequired

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

• childobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• attachmentsarray of objectrequired

  • idstring (uuid)required
  • filenamestringrequired
  • contentTypestringrequired
  • sizeBytesnumberrequired
• approvalRequestIdstring (uuid) or nullrequired
• cancellationRequestIdstring (uuid) or nullrequired
• onBehalfbooleanrequired
• cancelReasonstring | nullrequired
• createdAtstringrequired
• decidedAtstring | nullrequired
• daysarray of object

  • datestringrequired
  • sessionenumrequired

    one of "full", "am", "pm"

  • quantitynumberrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 leave_overlap
• 422 insufficient_balance, not_eligible

GET/api/v1/leave/requests/{id}

Get a leave request

Access

Permission leave:read

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• typeobjectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
• startDatestringrequired
• endDatestringrequired
• startSessionenumrequired

  one of "full", "am", "pm"

• endSessionenumrequired

  one of "full", "am", "pm"

• unitenumrequired

  one of "days", "hours"

• quantitynumberrequired
• reasonstring | nullrequired
• statusenumrequired

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

• childobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• attachmentsarray of objectrequired

  • idstring (uuid)required
  • filenamestringrequired
  • contentTypestringrequired
  • sizeBytesnumberrequired
• approvalRequestIdstring (uuid) or nullrequired
• cancellationRequestIdstring (uuid) or nullrequired
• onBehalfbooleanrequired
• cancelReasonstring | nullrequired
• createdAtstringrequired
• decidedAtstring | nullrequired
• daysarray of object

  • datestringrequired
  • sessionenumrequired

    one of "full", "am", "pm"

  • quantitynumberrequired

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

POST/api/v1/leave/requests/{id}/attachments

Attach files (such as an MC) to a pending or approved leave request

Access

Permission leave:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• attachmentsarray of objectrequired

  • filenamestringrequired

    min length 1 · max length 120

  • contentTypeenumrequired

    one of "application/pdf", "image/jpeg", "image/png", "image/webp", "image/heic"

  • dataBase64stringrequired

    min length 1 · max length 6990571

Responses

200 Success. object

• idstring (uuid)required
• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• typeobjectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
• startDatestringrequired
• endDatestringrequired
• startSessionenumrequired

  one of "full", "am", "pm"

• endSessionenumrequired

  one of "full", "am", "pm"

• unitenumrequired

  one of "days", "hours"

• quantitynumberrequired
• reasonstring | nullrequired
• statusenumrequired

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

• childobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• attachmentsarray of objectrequired

  • idstring (uuid)required
  • filenamestringrequired
  • contentTypestringrequired
  • sizeBytesnumberrequired
• approvalRequestIdstring (uuid) or nullrequired
• cancellationRequestIdstring (uuid) or nullrequired
• onBehalfbooleanrequired
• cancelReasonstring | nullrequired
• createdAtstringrequired
• decidedAtstring | nullrequired
• daysarray of object

  • datestringrequired
  • sessionenumrequired

    one of "full", "am", "pm"

  • quantitynumberrequired

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

GET/api/v1/leave/requests/{id}/attachments/{attachmentId}

Download an attachment (requester, approvers, owners and HR admins only: medical)

Access

Permission leave:read

Parameters

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

Responses

200 The file application/octet-stream

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

POST/api/v1/leave/requests/{id}/cancel

Cancel approved leave (sent for approval; owners and HR admins may cancel directly)

Access

Permission leave:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• reasonstring or null

  max length 300

• directboolean

  default false

Responses

200 Success. object

• idstring (uuid)required
• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• typeobjectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
• startDatestringrequired
• endDatestringrequired
• startSessionenumrequired

  one of "full", "am", "pm"

• endSessionenumrequired

  one of "full", "am", "pm"

• unitenumrequired

  one of "days", "hours"

• quantitynumberrequired
• reasonstring | nullrequired
• statusenumrequired

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

• childobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• attachmentsarray of objectrequired

  • idstring (uuid)required
  • filenamestringrequired
  • contentTypestringrequired
  • sizeBytesnumberrequired
• approvalRequestIdstring (uuid) or nullrequired
• cancellationRequestIdstring (uuid) or nullrequired
• onBehalfbooleanrequired
• cancelReasonstring | nullrequired
• createdAtstringrequired
• decidedAtstring | nullrequired
• daysarray of object

  • datestringrequired
  • sessionenumrequired

    one of "full", "am", "pm"

  • quantitynumberrequired

• 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

POST/api/v1/leave/requests/{id}/withdraw

Withdraw a pending leave request

Access

Permission leave:create

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• employeeobjectrequired

  • idstring (uuid)required
  • namestringrequired
• typeobjectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
• startDatestringrequired
• endDatestringrequired
• startSessionenumrequired

  one of "full", "am", "pm"

• endSessionenumrequired

  one of "full", "am", "pm"

• unitenumrequired

  one of "days", "hours"

• quantitynumberrequired
• reasonstring | nullrequired
• statusenumrequired

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

• childobject or nullrequired

  • idstring (uuid)required
  • namestringrequired
• attachmentsarray of objectrequired

  • idstring (uuid)required
  • filenamestringrequired
  • contentTypestringrequired
  • sizeBytesnumberrequired
• approvalRequestIdstring (uuid) or nullrequired
• cancellationRequestIdstring (uuid) or nullrequired
• onBehalfbooleanrequired
• cancelReasonstring | nullrequired
• createdAtstringrequired
• decidedAtstring | nullrequired
• daysarray of object

  • datestringrequired
  • sessionenumrequired

    one of "full", "am", "pm"

  • quantitynumberrequired

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

GET/api/v1/leave/settings

Leave settings (holidays on off days, no-pay leave and service, part-time reference)

Access

Permission policies:read

Responses

200 Success. object

• offDayHolidayenumrequired

  one of "extra_pay", "next_working_day"

• unpaidServiceRuleenumrequired

  one of "none", "whole_month", "any_day"

• fullTimeScheduleIdstring (uuid) or nullrequired

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

PUT/api/v1/leave/settings

Update leave settings

Access

Permission policies:update

Request body

application/json, object, required

• offDayHolidayenumrequired

  one of "extra_pay", "next_working_day"

• unpaidServiceRuleenumrequired

  one of "none", "whole_month", "any_day"

• fullTimeScheduleIdstring (uuid) or nullrequired

Responses

200 Success. object

• offDayHolidayenumrequired

  one of "extra_pay", "next_working_day"

• unpaidServiceRuleenumrequired

  one of "none", "whole_month", "any_day"

• fullTimeScheduleIdstring (uuid) or nullrequired

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

GET/api/v1/leave/types

List the leave types employees can apply for

Access

Any signed-in member (own data only)

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • codestringrequired
  • namestringrequired
  • statutoryCodestring | nullrequired
  • paidbooleanrequired
  • halfDaysbooleanrequired
  • attachmentenumrequired

    one of "none", "optional", "required"

  • attachmentLabelstring | nullrequired
  • sensitivebooleanrequired
  • needsChildbooleanrequired
  • perChildbooleanrequired
  • unlimitedbooleanrequired
  • archivedbooleanrequired
  • encashablebooleanrequired
  • employeeEncashmentRequestsbooleanrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required