# 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](https://developer.paycaptain.com/rules#approval) records may be sent. To withdraw a shift, [archive it](https://developer.paycaptain.com/rules#archiving).

Machine-readable: [JSON Schema](https://developer.paycaptain.com/schemas/shift.schema.json) · [OpenAPI](https://developer.paycaptain.com/openapi.json)

## Identity

### `shiftId`

Your identifier for the shift record.

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

### `company`

Company code issued by the PayCaptain team.

- Type: string
- Required
- Rule: Must match your PayCaptain company code exactly.
- Example: `"ABC"`

### `hrEmployeeId`

The person who worked the shift.

- Type: string
- Required
- Rule: Must match an employee already sent to PayCaptain.
- Example: `"9876543210"`

### `payrollCode`

The employment the shift belongs to.

- Type: string
- Required
- Rule: Must match that person's active employment.
- Example: `"123"`

## Shift

### `date`

Date of the shift.

- Type: string
- Required
- Format: YYYY-MM-DD
- Example: `"2026-11-02"`

### `type`

What the record represents.

- Type: string
- Required
- Rule: Exactly one of the allowed values.
- Allowed values: `"Working"`, `"Holiday"`, `"Sickness"`, `"Unpaid Leave"`
- Example: `"Working"`

### `payBasis`

How the shift is paid.

- Type: string
- Required
- Rule: Exactly one of the allowed values. Decides whether units are hours or days.
- Allowed values: `"Hourly"`, `"Daily"`
- Example: `"Hourly"`

### `units`

Quantity worked.

- Type: number
- Required
- Rule: Hours when payBasis is "Hourly", days when "Daily".
- Range: minimum 0
- Example: `7.5`

### `rate`

Rate of pay for this shift.

- Type: number
- Required
- Rule: Per hour or per day, matching payBasis.
- Range: minimum 0
- Example: `15.25`

### `sicknessDayType`

Whether a sickness day is a qualifying day.

- Type: string
- Optional
- 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"`

### `reason`

Reason for an absence, mainly for sickness records.

- Type: string
- Optional
- Example: `"Flu"`

### `archived`

Archive the shift so it is not paid.

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

## Cost allocation

### `location`

Location worked.

- Type: string
- Optional
- Example: `"Baker Street"`

### `department`

Department worked.

- Type: string
- Optional
- Example: `"Marketing"`

### `team`

Team worked.

- Type: string
- Optional
- Example: `"Content"`

### `job`

Job worked.

- Type: string
- Optional
- Example: `"Content Marketing"`


## Minimal valid record

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