Field validation

Shift fields

Every field accepted by POST /shift, with its validation rule.

Send one JSON object per shift or absence day to POST /shift. Only approved records may be sent. To withdraw a shift, archive it.

Machine-readable: JSON Schema · OpenAPI

Identity#

shiftIdstringRequired

Your identifier for the shift record.

Rule: Unique in your system. Resubmitting the same shiftId updates the record.
Example: "SH-000481"

companystringRequired

Company code issued by the PayCaptain team.

Rule: Must match your PayCaptain company code exactly.
Example: "ABC"

hrEmployeeIdstringRequired

The person who worked the shift.

Rule: Must match an employee already sent to PayCaptain.
Example: "9876543210"

payrollCodestringRequired

The employment the shift belongs to.

Rule: Must match that person's active employment.
Example: "123"

Shift#

datestringRequired

Date of the shift.

Format: YYYY-MM-DD
Example: "2026-11-02"

typestringRequired

What the record represents.

Rule: Exactly one of the allowed values.
Allowed values: "Working" "Holiday" "Sickness" "Unpaid Leave"
Example: "Working"

payBasisstringRequired

How the shift is paid.

Rule: Exactly one of the allowed values. Decides whether units are hours or days.
Allowed values: "Hourly" "Daily"
Example: "Hourly"

unitsnumberRequired

Quantity worked.

Rule: Hours when payBasis is "Hourly", days when "Daily".
Range: minimum 0
Example: 7.5

ratenumberRequired

Rate of pay for this shift.

Rule: Per hour or per day, matching payBasis.
Range: minimum 0
Example: 15.25

sicknessDayTypestringOptional

Whether a sickness day is a qualifying day.

Rule: Only meaningful when type is "Sickness". "Qualifying", "Q" and "Y" mean a qualifying day; "Non Qualifying" and "N" mean it is not.
Allowed values: "Qualifying" "Q" "Y" "Non Qualifying" "N"
Example: "Qualifying"

reasonstringOptional

Reason for an absence, mainly for sickness records.

Example: "Flu"

archivedbooleanOptional

Archive the shift so it is not paid.

Rule: Send true with the same shiftId to remove the shift from payroll. Records are archived, never deleted.
Default: false
Example: false

Cost allocation#

locationstringOptional

Location worked.

Example: "Baker Street"

departmentstringOptional

Department worked.

Example: "Marketing"

teamstringOptional

Team worked.

Example: "Content"

jobstringOptional

Job worked.

Example: "Content Marketing"

Minimal valid record#

{
  "shiftId": "SH-000481",
  "company": "ABC",
  "hrEmployeeId": "9876543210",
  "payrollCode": "123",
  "date": "2026-11-02",
  "type": "Working",
  "payBasis": "Hourly",
  "units": 7.5,
  "rate": 15.25
}