Payroll API

26 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/payroll/allowance-settings

CPF and pro-ration treatment of each allowance type

Access

Permission payroll:read

Responses

200 Success. object

• itemsarray of objectrequired

  • allowanceTypeIdstring (uuid)required
  • codestringrequired
  • namestringrequired
  • cpfLiablebooleanrequired
  • proratebooleanrequired
  • grossRateIncludedboolean | nullrequired

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

PUT/api/v1/payroll/allowance-settings/{allowanceTypeId}

Set whether an allowance type is CPF-liable and pro-rated

Access

Permission payroll:update

Parameters

Name	In	Type	Required
allowanceTypeId	path	string (uuid)	yes

Request body

application/json, object, required

• cpfLiablebooleanrequired
• proratebooleanrequired
• grossRateIncludedboolean | null

Responses

200 Success. object

• allowanceTypeIdstring (uuid)required
• codestringrequired
• namestringrequired
• cpfLiablebooleanrequired
• proratebooleanrequired
• grossRateIncludedboolean | nullrequired

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

GET/api/v1/payroll/runs

List payroll runs, newest month first

Access

Permission payroll:read

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • kindenumrequired

    one of "regular", "off_cycle", "adjustment"

  • offCycleReasonenum or nullrequired

    one of "final_pay", "bonus"

  • monthstringrequired
  • payDatestring (date)required
  • statusenumrequired

    one of "draft", "in_review", "approved", "paid"

  • supersededByRunIdstring (uuid) or nullrequired
  • adjustsRunIdstring (uuid) or nullrequired
  • releasedAtstring | nullrequired
  • totalsobject or nullrequired

    • headcountintegerrequired

      min -9007199254740991

    • grossCentsintegerrequired

      min -9007199254740991

    • netCentsintegerrequired

      min -9007199254740991

    • netPayableCentsintegerrequired

      min -9007199254740991

    • reimbursementsCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeCentsintegerrequired

      min -9007199254740991

    • cpfEmployerCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeShareAbsorbedCentsinteger

      min -9007199254740991

    • cpfAwRecoveredCentsinteger

      min -9007199254740991

    • cpfTotalChargedCentsintegerrequired

      min -9007199254740991

    • shgCentsintegerrequired

      min -9007199254740991

    • shgChargedByFundobjectrequired
    • shgDonorsobjectrequired
    • sdlChargedCentsintegerrequired

      min -9007199254740991

    • sdlMonthCentsintegerrequired

      min -9007199254740991

    • fwlCentsintegerrequired

      min -9007199254740991

    • employerCostCentsintegerrequired

      min -9007199254740991

    • blockingintegerrequired

      min -9007199254740991

    • warningsintegerrequired

      min -9007199254740991

  • computedAtstring | nullrequired

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

POST/api/v1/payroll/runs

Create a regular or off-cycle (final pay, bonus) payroll run

Access

Permission payroll:create

Request body

application/json, object, required

• kindenumrequired

  one of "regular", "off_cycle"

• monthstringrequired
• payDatestring (date) or null
• offCycleReasonenum or null

  one of "final_pay", "bonus"

• employeeIdsarray of string (uuid) or null

Responses

201 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

GET/api/v1/payroll/runs/{runId}

Run overview: issues first, totals, changes since last month, and the employee table

Access

Permission payroll:read

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 Success. object

• runobjectrequired

  • idstring (uuid)required
  • kindenumrequired

    one of "regular", "off_cycle", "adjustment"

  • offCycleReasonenum or nullrequired

    one of "final_pay", "bonus"

  • monthstringrequired
  • periodStartstring (date)required
  • periodEndstring (date)required
  • payDatestring (date)required
  • statusenumrequired

    one of "draft", "in_review", "approved", "paid"

  • employeeIdsarray of string (uuid) or nullrequired
  • adjustsRunIdstring (uuid) or nullrequired
  • supersededByRunIdstring (uuid) or nullrequired
  • reopenReasonstring | nullrequired
  • approvalRequestIdstring | nullrequired
  • submittedBystring (uuid) or nullrequired
  • submittedAtstring | nullrequired
  • decidedBystring (uuid) or nullrequired
  • decidedAtstring | nullrequired
  • decisionCommentstring | nullrequired
  • selfApprovedbooleanrequired
  • computedAtstring | nullrequired
  • inputHashstring | nullrequired
  • resultHashstring | nullrequired
  • totalsobject or nullrequired

    • headcountintegerrequired

      min -9007199254740991

    • grossCentsintegerrequired

      min -9007199254740991

    • netCentsintegerrequired

      min -9007199254740991

    • netPayableCentsintegerrequired

      min -9007199254740991

    • reimbursementsCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeCentsintegerrequired

      min -9007199254740991

    • cpfEmployerCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeShareAbsorbedCentsinteger

      min -9007199254740991

    • cpfAwRecoveredCentsinteger

      min -9007199254740991

    • cpfTotalChargedCentsintegerrequired

      min -9007199254740991

    • shgCentsintegerrequired

      min -9007199254740991

    • shgChargedByFundobjectrequired
    • shgDonorsobjectrequired
    • sdlChargedCentsintegerrequired

      min -9007199254740991

    • sdlMonthCentsintegerrequired

      min -9007199254740991

    • fwlCentsintegerrequired

      min -9007199254740991

    • employerCostCentsintegerrequired

      min -9007199254740991

    • blockingintegerrequired

      min -9007199254740991

    • warningsintegerrequired

      min -9007199254740991

  • releasedAtstring | nullrequired
  • paidAtstring | nullrequired
  • createdAtstringrequired
  • inputsChangedSinceComputebooleanrequired
• rowsarray of objectrequired

  • payslipIdstring (uuid)required
  • employeeIdstring (uuid)required
  • employeeNumberstringrequired
  • namestringrequired
  • departmentstring | nullrequired
  • basicCentsintegerrequired

    min -9007199254740991

  • allowancesCentsintegerrequired

    min -9007199254740991

  • overtimeCentsintegerrequired

    min -9007199254740991

  • additionalCentsintegerrequired

    min -9007199254740991

  • nplCentsintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • otherDeductionsCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

  • flagsarray of stringrequired
• issuesarray of objectrequired

  • codestringrequired
  • severityenumrequired

    one of "info", "warning", "blocking"

  • messagestringrequired
  • sourcestring | nullrequired
  • employeeIdstring (uuid) or nullrequired
  • employeeNamestring | nullrequired
• changesobjectrequired

  • comparedWithobject or nullrequired

    • runIdstring (uuid)required
    • monthstringrequired
  • headlinestringrequired
  • itemsarray of objectrequired

    • kindenumrequired

      one of "joined", "left", "basic_changed", "new_item", "net_changed", "not_in_run", "residency"

    • employeeIdstring (uuid)required
    • namestringrequired
    • textstringrequired
• adjustmentobject or nullrequired

  • ofRunIdstring (uuid)required
  • ofMonthstringrequired
• supersededBystring (uuid) or nullrequired

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

PATCH/api/v1/payroll/runs/{runId}

Change a draft run's pay date

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Request body

application/json, object, required

• payDatestring (date)required

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

DELETE/api/v1/payroll/runs/{runId}

Delete a draft run

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	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/payroll/runs/{runId}/compute

Compute every employee's pay from the current records and the run's items

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

GET/api/v1/payroll/runs/{runId}/employees/{employeeId}

One employee in a run: inputs, every line, the full CPF/SDL/SHG working and the issues

Access

Permission payroll:read

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes
employeeId	path	string (uuid)	yes

Responses

200 Success. object

• runobjectrequired

  • idstring (uuid)required
  • kindenumrequired

    one of "regular", "off_cycle", "adjustment"

  • offCycleReasonenum or nullrequired

    one of "final_pay", "bonus"

  • monthstringrequired
  • payDatestring (date)required
  • statusenumrequired

    one of "draft", "in_review", "approved", "paid"

  • supersededByRunIdstring (uuid) or nullrequired
  • adjustsRunIdstring (uuid) or nullrequired
  • releasedAtstring | nullrequired
  • totalsobject or nullrequired

    • headcountintegerrequired

      min -9007199254740991

    • grossCentsintegerrequired

      min -9007199254740991

    • netCentsintegerrequired

      min -9007199254740991

    • netPayableCentsintegerrequired

      min -9007199254740991

    • reimbursementsCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeCentsintegerrequired

      min -9007199254740991

    • cpfEmployerCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeShareAbsorbedCentsinteger

      min -9007199254740991

    • cpfAwRecoveredCentsinteger

      min -9007199254740991

    • cpfTotalChargedCentsintegerrequired

      min -9007199254740991

    • shgCentsintegerrequired

      min -9007199254740991

    • shgChargedByFundobjectrequired
    • shgDonorsobjectrequired
    • sdlChargedCentsintegerrequired

      min -9007199254740991

    • sdlMonthCentsintegerrequired

      min -9007199254740991

    • fwlCentsintegerrequired

      min -9007199254740991

    • employerCostCentsintegerrequired

      min -9007199254740991

    • blockingintegerrequired

      min -9007199254740991

    • warningsintegerrequired

      min -9007199254740991

  • computedAtstring | nullrequired
• employeeIdstring (uuid)required
• payslipIdstring (uuid) or nullrequired
• employeeNamestring | nullrequired
• inputobject or nullrequired
• inputHashstring | nullrequired
• resultobject or nullrequired

  • engineVersionintegerrequired

    min -9007199254740991

  • linesarray of objectrequired

    • codestringrequired
    • kindenumrequired

      one of "earning", "deduction", "reimbursement", "employer"

    • categorystringrequired
    • labelstringrequired
    • amountCentsintegerrequired

      min -9007199254740991

    • wageClassenum or nullrequired

      one of "OW", "AW"

    • cpfLiablebooleanrequired
    • detailstring | nullrequired
    • itemIdstring | nullrequired
  • totalsobjectrequired
  • monthobjectrequired

    • owCpfCentsintegerrequired

      min -9007199254740991

    • awCpfCentsintegerrequired

      min -9007199254740991

    • totalWagesCentsintegerrequired

      min -9007199254740991

    • cpfTotalCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeCentsintegerrequired

      min -9007199254740991

    • cpfEmployerCentsintegerrequired

      min -9007199254740991

    • shgCentsobjectrequired
    • sdlUnits1e4Centintegerrequired

      min -9007199254740991

  • chargedobjectrequired

    • cpfTotalCentsintegerrequired

      min -9007199254740991

    • cpfEmployeeCentsintegerrequired

      min -9007199254740991

    • cpfAwTopUpEmployeeCentsinteger

      min -9007199254740991

    • cpfEmployerCentsintegerrequired

      min -9007199254740991

    • shgCentsobjectrequired
    • sdlUnits1e4Centintegerrequired

      min -9007199254740991

  • cpfobject or nullrequired

    • residencyCategorystringrequired
    • ageBandstring | nullrequired
    • ageBandLabelstring | nullrequired
    • rateTableIdstring | nullrequired
    • wageBandstring | nullrequired
    • owSubjectCentsintegerrequired

      min -9007199254740991

    • awSubjectCentsintegerrequired

      min -9007199254740991

    • awNotSubjectCentsintegerrequired

      min -9007199254740991

    • awCeilingobject or nullrequired

      • basisstringrequired
      • annualOwSubjectCentsintegerrequired

        min -9007199254740991

      • annualAwCeilingCentsintegerrequired

        min -9007199254740991

      • headroomBeforeCentsintegerrequired

        min -9007199254740991

      • headroomAfterCentsintegerrequired

        min -9007199254740991

    • priorAwShortfallCentsintegerrequired

      min -9007199254740991

    • priorAwExcessCentsintegerrequired

      min -9007199254740991

    • exactTotalstringrequired
    • exactEmployeestringrequired
  • shgFundsarray of stringrequired
  • overtimeobject or nullrequired

    • minutesintegerrequired

      min -9007199254740991

    • periodsarray of objectrequired

      • labelstringrequired
      • periodStartstring (date) or nullrequired
      • periodEndstring (date) or nullrequired
      • minutesintegerrequired

        min -9007199254740991

      • payCentsintegerrequired

        min -9007199254740991

  • awTopUpobject or null

    • employeeShareCentsintegerrequired

      min -9007199254740991

    • recoveredThisRunCentsintegerrequired

      min -9007199254740991

    • recoveredEarlierCentsintegerrequired

      min -9007199254740991

    • absorbedCentsintegerrequired

      min -9007199254740991

    • deadlinestring (date)required
  • hourlyobject or nullrequired

    • rateCentsintegerrequired

      min -9007199254740991

    • minutesintegerrequired

      min -9007199254740991

  • rulesarray of objectrequired

    • familystringrequired
    • idstringrequired
    • effectiveFromstring (date)required
    • effectiveTostring (date) or nullrequired
    • sourcestringrequired
  • workingarray of objectrequired

    • sectionstringrequired
    • codestringrequired
    • textstringrequired
  • issuesarray of objectrequired

    • codestringrequired
    • severityenumrequired

      one of "info", "warning", "blocking"

    • messagestringrequired
    • sourcestring | nullrequired
  • stateAfterobjectrequired

    • owSubjectCentsintegerrequired

      min -9007199254740991

    • awPaymentsarray of objectrequired

      • payableMonthstringrequired
      • owCentsintegerrequired

        min -9007199254740991

      • awPayableCentsintegerrequired

        min -9007199254740991

      • awSubjectCentsintegerrequired

        min -9007199254740991

      • residencyobject
• resultHashstring | nullrequired
• itemsarray of objectrequired

  • idstring (uuid)required
  • employeeIdstring (uuid)required
  • kindenumrequired

    one of "bonus", "commission", "backpay", "other_earning", "overtime", "unpaid_leave", "hours", "deduction", "scheduled_days", "days_worked", "cpf_aw_recovery"

  • labelstringrequired
  • amountCentsinteger or nullrequired

    min -9007199254740991

  • wageClassenum or nullrequired

    one of "OW", "AW"

  • cpfLiablebooleanrequired
  • awPayableDatestring (date) or nullrequired
  • minutesinteger or nullrequired

    min -9007199254740991

  • daysnumber | nullrequired
  • datestring (date) or nullrequired
  • periodStartstring (date) or nullrequired
  • periodEndstring (date) or nullrequired
  • deductionCategoryenum or nullrequired

    one of "absence", "damage_loss", "accommodation", "amenities", "advance", "loan", "unearned_benefit", "overpayment", "cooperative", "consented", "court_order"

  • sourceenumrequired

    one of "manual", "attendance"

  • copiedFromItemIdstring (uuid) or nullrequired
  • overtimeSourceIdstring (uuid) or nullrequired
  • holidayDatestring (date) or nullrequired

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

GET/api/v1/payroll/runs/{runId}/files/bank

Generic ISO 20022 pain.001.001.03 salary credit-transfer file (not a bank-specific format)

Open-standard file for banks that accept ISO 20022 pain.001 uploads. Each bank's message guide (service level, charge bearer, BIC length) is not applied; test the file with your bank before first use. Excluded employees are listed in the x-crowhr-excluded header (URL-encoded JSON).

Access

Permission payroll:read

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 pain.001.001.03 XML application/xml

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

GET/api/v1/payroll/runs/{runId}/files/cpf-ezpay

CPF EZPay (FTP) submission file for the amounts this run charged

Fixed-width file per CPF Board's CPF EZPay (FTP) File Specifications (16 Jan 2025), for upload in CPF EZPay. Employees left out (e.g. SHG for foreigners without a CPF account) are listed in the x-crowhr-excluded header (URL-encoded JSON).

Access

Permission payroll:read

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 CPF EZPay .DTL file text/plain

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

POST/api/v1/payroll/runs/{runId}/items

Add a pay item (bonus, commission, back pay, overtime, no-pay leave, hours, deduction) to a draft run

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Request body

application/json, object, required

• overtimeSourceIdstring (uuid) or null
• holidayDatestring (date) or null
• employeeIdstring (uuid)required
• kindenumrequired

  one of "bonus", "commission", "backpay", "other_earning", "overtime", "unpaid_leave", "hours", "deduction", "scheduled_days", "days_worked", "cpf_aw_recovery"

• labelstringrequired

  min length 1 · max length 80

• amountCentsinteger or null

  min 0

• wageClassenum or null

  one of "OW", "AW"

• cpfLiableboolean
• awPayableDatestring (date) or null
• minutesinteger or null

  max 44640

• daysnumber or null

  max 31

• datestring (date) or null
• periodStartstring (date) or null
• periodEndstring (date) or null
• deductionCategoryenum or null

  one of "absence", "damage_loss", "accommodation", "amenities", "advance", "loan", "unearned_benefit", "overpayment", "cooperative", "consented", "court_order"

Responses

201 Success. object

• idstring (uuid)required

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

PUT/api/v1/payroll/runs/{runId}/items/{itemId}

Replace a pay item on a draft run

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes
itemId	path	string (uuid)	yes

Request body

application/json, object, required

• overtimeSourceIdstring (uuid) or null
• holidayDatestring (date) or null
• employeeIdstring (uuid)required
• kindenumrequired

  one of "bonus", "commission", "backpay", "other_earning", "overtime", "unpaid_leave", "hours", "deduction", "scheduled_days", "days_worked", "cpf_aw_recovery"

• labelstringrequired

  min length 1 · max length 80

• amountCentsinteger or null

  min 0

• wageClassenum or null

  one of "OW", "AW"

• cpfLiableboolean
• awPayableDatestring (date) or null
• minutesinteger or null

  max 44640

• daysnumber or null

  max 31

• datestring (date) or null
• periodStartstring (date) or null
• periodEndstring (date) or null
• deductionCategoryenum or null

  one of "absence", "damage_loss", "accommodation", "amenities", "advance", "loan", "unearned_benefit", "overpayment", "cooperative", "consented", "court_order"

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

DELETE/api/v1/payroll/runs/{runId}/items/{itemId}

Remove a pay item from a draft run

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes
itemId	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/payroll/runs/{runId}/mark-paid

Record that an approved run has been paid (locks it)

Access

Permission payroll:finalise

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

GET/api/v1/payroll/runs/{runId}/payslips/{payslipId}

A payslip of a run, as the employee will see it

Access

Permission payroll:read

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes
payslipId	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• runIdstring (uuid)required
• runKindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• titlestringrequired
• revisionobject or nullrequired

  • ofRunIdstring (uuid)required
  • previouslyPaidCentsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• employerobjectrequired

  • legalNamestringrequired
• employeeobjectrequired

  • namestringrequired
  • employeeNumberstringrequired
  • idMaskedstringrequired
  • jobTitlestring | nullrequired
  • departmentstring | nullrequired
• payDatestring (date)required
• periodStartstring (date)required
• periodEndstring (date)required
• basicobject or nullrequired

  • amountCentsintegerrequired

    min -9007199254740991

  • detailstring | nullrequired
  • hourlyobject or nullrequired

    • rateCentsintegerrequired

      min -9007199254740991

    • hoursnumberrequired
• allowancesarray of objectrequired

  • labelstringrequired
  • amountCentsintegerrequired

    min -9007199254740991

  • detailstring | nullrequired
• additionalarray of objectrequired

  • labelstringrequired
  • amountCentsintegerrequired

    min -9007199254740991

  • detailstring | nullrequired
• overtimeobject or nullrequired

  • hoursnumberrequired
  • payCentsintegerrequired

    min -9007199254740991

  • periodsarray of objectrequired

    • labelstringrequired
    • hoursnumberrequired
    • payCentsintegerrequired

      min -9007199254740991

    • periodStartstring (date) or nullrequired
    • periodEndstring (date) or nullrequired
    • differsFromSalaryPeriodbooleanrequired
• deductionsarray of objectrequired

  • labelstringrequired
  • amountCentsintegerrequired

    min -9007199254740991

  • detailstring | nullrequired
  • typeenumrequired

    one of "fixed", "ad_hoc"

• reimbursementsarray of objectrequired

  • labelstringrequired
  • amountCentsintegerrequired

    min -9007199254740991

  • detailstring | nullrequired
• grossCentsintegerrequired

  min -9007199254740991

• totalDeductionsCentsintegerrequired

  min -9007199254740991

• netCentsintegerrequired

  min -9007199254740991

• netPayableCentsintegerrequired

  min -9007199254740991

• employerCpfCentsintegerrequired

  min -9007199254740991

• cpfobject or nullrequired

  • rateTableIdstring | nullrequired
  • rateTableLabelstring | nullrequired
  • ageBandstring | nullrequired
  • residencystringrequired
  • owSubjectCentsintegerrequired

    min -9007199254740991

  • awSubjectCentsintegerrequired

    min -9007199254740991

• shgFundsarray of stringrequired
• ytdobjectrequired

  • yearstringrequired
  • awSubjectCentsintegerrequired

    min -9007199254740991

  • owSubjectCentsintegerrequired

    min -9007199254740991

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

GET/api/v1/payroll/runs/{runId}/payslips/{payslipId}/pdf

Download a payslip of a run as PDF (preview before release)

Access

Permission payroll:read

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes
payslipId	path	string (uuid)	yes

Responses

200 Payslip PDF application/pdf

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

POST/api/v1/payroll/runs/{runId}/release

Release an approved run's payslips to employees

Access

Permission payroll:finalise

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

POST/api/v1/payroll/runs/{runId}/reopen

Reopen an approved or paid run as a new adjustment run (the original is never changed)

Access

Permission payroll:create

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Request body

application/json, object, required

• reasonstringrequired

  max length 500

Responses

201 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

POST/api/v1/payroll/runs/{runId}/return-to-draft

Return an approved, unpaid run to draft to recompute and approve it again

For a change after approval that must not be paid as an adjustment, such as an employee's new bank account: the bank file refuses a run whose payees changed after it was computed. Payslips are hidden again until the run is re-approved and released.

Access

Permission payroll:finalise

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Request body

application/json, object, required

• reasonstringrequired

  max length 500

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

POST/api/v1/payroll/runs/{runId}/submit

Submit a computed run with no blocking issues for approval

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

POST/api/v1/payroll/runs/{runId}/withdraw

Withdraw a run in review back to draft

Access

Permission payroll:update

Parameters

Name	In	Type	Required
runId	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• kindenumrequired

  one of "regular", "off_cycle", "adjustment"

• offCycleReasonenum or nullrequired

  one of "final_pay", "bonus"

• monthstringrequired
• periodStartstring (date)required
• periodEndstring (date)required
• payDatestring (date)required
• statusenumrequired

  one of "draft", "in_review", "approved", "paid"

• employeeIdsarray of string (uuid) or nullrequired
• adjustsRunIdstring (uuid) or nullrequired
• supersededByRunIdstring (uuid) or nullrequired
• reopenReasonstring | nullrequired
• approvalRequestIdstring | nullrequired
• submittedBystring (uuid) or nullrequired
• submittedAtstring | nullrequired
• decidedBystring (uuid) or nullrequired
• decidedAtstring | nullrequired
• decisionCommentstring | nullrequired
• selfApprovedbooleanrequired
• computedAtstring | nullrequired
• inputHashstring | nullrequired
• resultHashstring | nullrequired
• totalsobject or nullrequired

  • headcountintegerrequired

    min -9007199254740991

  • grossCentsintegerrequired

    min -9007199254740991

  • netCentsintegerrequired

    min -9007199254740991

  • netPayableCentsintegerrequired

    min -9007199254740991

  • reimbursementsCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeCentsintegerrequired

    min -9007199254740991

  • cpfEmployerCentsintegerrequired

    min -9007199254740991

  • cpfEmployeeShareAbsorbedCentsinteger

    min -9007199254740991

  • cpfAwRecoveredCentsinteger

    min -9007199254740991

  • cpfTotalChargedCentsintegerrequired

    min -9007199254740991

  • shgCentsintegerrequired

    min -9007199254740991

  • shgChargedByFundobjectrequired
  • shgDonorsobjectrequired
  • sdlChargedCentsintegerrequired

    min -9007199254740991

  • sdlMonthCentsintegerrequired

    min -9007199254740991

  • fwlCentsintegerrequired

    min -9007199254740991

  • employerCostCentsintegerrequired

    min -9007199254740991

  • blockingintegerrequired

    min -9007199254740991

  • warningsintegerrequired

    min -9007199254740991

• releasedAtstring | nullrequired
• paidAtstring | nullrequired
• createdAtstringrequired
• inputsChangedSinceComputebooleanrequired

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

GET/api/v1/payroll/settings

Payroll settings (pay day, release, CPF advice code, levy and bank file defaults)

Access

Permission payroll:read

Responses

200 Success. object

• payDayinteger or nullrequired

  min -9007199254740991

• cutoffDayinteger or nullrequired

  min -9007199254740991

• autoReleasebooleanrequired
• cpfAdviceCodestringrequired
• fwlSectorstring | nullrequired
• fwlTierstring | nullrequired
• fwlSkillstring | nullrequired
• debitBankBicstring | nullrequired
• debitAccountMaskedstring | nullrequired
• debitAccountNamestring | nullrequired

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

PUT/api/v1/payroll/settings

Update payroll settings

Access

Permission payroll:update

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Request body

application/json, object, required

• cutoffDayinteger or null

  min 1 · max 31

• payDayinteger or null

  min 1 · max 31

• autoReleaseboolean
• cpfAdviceCodestring
• fwlSectorstring or null

  max length 40

• fwlTierstring or null

  max length 40

• fwlSkillstring or null

  max length 40

• debitBankBicstring or null
• debitAccountNumberstring or null
• debitAccountNamestring or null

  max length 70

Responses

200 Success. object

• payDayinteger or nullrequired

  min -9007199254740991

• cutoffDayinteger or nullrequired

  min -9007199254740991

• autoReleasebooleanrequired
• cpfAdviceCodestringrequired
• fwlSectorstring | nullrequired
• fwlTierstring | nullrequired
• fwlSkillstring | nullrequired
• debitBankBicstring | nullrequired
• debitAccountMaskedstring | nullrequired
• debitAccountNamestring | nullrequired

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

GET/api/v1/payroll/years/{year}/ir8a

IR8A figures for an income year (whole dollars, masked IDs)

Preview of the IR8A records Crow HR can fill from approved payslips, in the parts (≤ 200 records) the file download produces. Appendix 8A is not produced (no benefits-in-kind are recorded). Direct submission through IRAS's AIS-API is not available.

Access

Permission payroll:read

Parameters

Name	In	Type	Required
year	path	integer	yes

Responses

200 Success. object

• yearintegerrequired

  min -9007199254740991

• yearOfAssessmentintegerrequired

  min -9007199254740991

• dueOnstring (date)required
• templateUrlstring (uri)required
• explanatoryNotesUrlstring (uri)required
• partsarray of objectrequired

  • partintegerrequired

    min -9007199254740991

  • recordsintegerrequired

    min -9007199254740991

• recordsarray of objectrequired

  • employeeIdstring (uuid)required
  • employeeNamestringrequired
  • idMaskedstringrequired
  • partintegerrequired

    min -9007199254740991

  • recordNointegerrequired

    min -9007199254740991

  • grossSalaryintegerrequired

    Whole dollars, cents dropped (IRAS income rounding)

    min -9007199254740991

  • bonusintegerrequired

    min -9007199254740991

  • allowancesintegerrequired

    min -9007199254740991

  • commissionintegerrequired

    min -9007199254740991

  • employeeCpfintegerrequired

    Whole dollars, rounded up (IRAS deduction rounding)

    min -9007199254740991

  • donationsintegerrequired

    min -9007199254740991

  • mbmfintegerrequired

    min -9007199254740991

  • commencedOnstring (date) or nullrequired
  • ceasedOnstring (date) or nullrequired
  • notesarray of objectrequired

    • codestringrequired
    • messagestringrequired
• excludedarray of objectrequired

  • employeeNamestringrequired
  • reasonstringrequired
• notesarray of objectrequired

  • codestringrequired
  • messagestringrequired

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

GET/api/v1/payroll/years/{year}/ir8a/file

IR8A rows for IRAS's IR8A import template (CSV, one part of ≤ 200 records)

Columns A–AR of the IR8A sheet of IRAS's IR8A Import Template (https://go.gov.sg/ir8a-import-template, version 1.0) with its header row: paste the data rows at row 6 of the template and import it in myTax Portal → Employment Income Records. Income is in whole dollars with cents dropped, deductions rounded up. Contains full NRIC/FIN numbers. Excluded employees are listed in the x-crowhr-excluded header (URL-encoded JSON).

Access

Permission payroll:read

Re-authentication

Signed in within the last 10 minutes, otherwise 403 reauth_required

Parameters

Name	In	Type	Required
year	path	integer	yes
part	query	integer	no

Responses

200 IR8A rows (CSV, UTF-8) text/csv

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