Data sync resources

This page lists the 33 resources of the data sync API. Every resource has a changed-since feed (/api/v1/sync/{resource}) and id reconciliation (/api/v1/sync/{resource}/ids). Read the guide first for how passes, deletions, include, files and the payroll rule work.

How to read this page

Each resource lists:

• Scope: which rows a key receives. "Own company" means the row's company is one of the key's companies. "Through the employee" means the row's employee belongs to one of the key's companies. "Group" means every key of the group receives every row.
• include: the opt-in names the resource accepts and the fields each adds. A name it does not accept gets 400.
• Content: whether /api/v1/sync/{resource}/{id}/content serves a file.
• Run listing: whether ?payroll_run_id=<id> lists every row of one payroll run.
• Page size: the largest limit. It is 1,000 (default 500) unless stated.

Field types:

Treat every field except id as nullable. An id that points at a row in a company outside the key's companies is null. Enum values are returned as stored; the values listed are the ones Hopshift writes today.

People

employees

One row per employee record, every status. Moving a person to another company creates a second record with a new id (see people with several employee records).

• Scope: own company.
• include: notes adds termination_reason (string), would_rehire (boolean, HR's judgement), scheduling_notes (string) and exclude_from_payroll_reason (string).
• Content: none. Run listing: no.

employee-events

Employment history: one row per event, such as a salary change, promotion, transfer or termination.

• Scope: own company (the event's company).
• include: notes adds reason (string) and, inside the values of status events, termination_reason and would_rehire.
• Content: none. Run listing: no.

previous_value and new_value keep only these keys, renamed to snake_case. They are null when none of the keys is present, and always null for other event types. Values are passed through as recorded, so their JSON types can differ between rows. Employee and company ids inside them are null when outside the key's companies.

salary-adjustments

Salary changes with their amounts.

• Scope: through the employee.
• include: notes adds reason (string).
• Content: none. Run listing: no.

transfers

Moves of an employee from one company to another. A completed transfer links the source employee record to the new record in the target company.

• Scope: either company: the key receives the transfer when the source or the target company is one of its companies.
• include: notes adds reason (string).
• Content: none. Run listing: no.

employee-locations

Outlet assignments: the outlets an employee is assigned to, with dates.

• Scope: through the employee.
• include: none. Content: none. Run listing: no.

Structure

companies

The companies of the group the key covers. Reporting lines are employees.manager_id; there is no separate resource for them.

• Scope: the key's companies.
• include: none. Content: none. Run listing: no.

locations

Outlets.

• Scope: own company.
• include: none. Content: none. Run listing: no.

departments

• Scope: own company.
• include: none. Content: none. Run listing: no.

positions

Job positions, such as Barista or Sous Chef.

• Scope: own company.
• include: none. Content: none. Run listing: no.

level-tiers

The group's level ladder that positions belong to.

• Scope: group.
• include: none. Content: none. Run listing: no.

Attendance

clock-records

Punches: clock-ins, clock-outs and breaks.

• Scope: own company (the company recorded on the punch). A punch at a host outlet can name an employee, outlet or roster of another company; those ids are null when that company is outside the key's companies.
• include:
  • notes adds notes (string), manager_notes (string) and approval_reason (string, the wording behind the approval outcome, such as a reviewer's rejection reason).
  • gps adds gps_location (string, the raw position as "lat,lng"), gps_accuracy (number, as reported by the device) and ip_address (string).
  • photos adds has_photo (boolean).
  • All opt-in fields are null when the punch's employee belongs to a company outside the key's companies.
• Content: the punch's face photo when has_photo is true. 404 when the punch or its employee is outside the key's companies, or there is no photo.
• Run listing: no.

clock-record-history

Status history of punches: one row per review step.

• Scope: through the punch's company.
• include: notes adds notes (string, the reviewer's text), null when the punch's employee belongs to a company outside the key's companies.
• Content: none. Run listing: no.

shifts

Rosters, including deleted ones: a deleted shift stays in the feed and in /ids with deleted_at set.

• Scope: own company.
• include: notes adds notes (string) and deletion_reason (string).
• Content: none. Run listing: no.

Shifts have no created_at or updated_at.

overtime-requests

• Scope: own company.
• include: notes adds reason (string, the employee's) and manager_notes (string).
• Content: none. Run listing: no.

attendance-corrections

Requests to correct punches, such as a missed clock-out.

• Scope: own company (the employee's payroll company). The punch, roster and outlet it names can belong to a host company; those ids are null when that company is outside the key's companies.
• include: notes adds reason (string, the employee's) and review_note (string, the reviewer's).
• Content: none. Run listing: no.

Leave

leave-requests

Medical certificates and other attachments are never served.

• Scope: own company.
• include: notes adds reason (string, the employee's) and manager_notes (string).
• Content: none. Run listing: no.

leave-request-history

Status history of leave requests.

• Scope: through the request's company.
• include: notes adds notes (string, the reviewer's text).
• Content: none. Run listing: no.

leave-types

The group's leave types and their rules. Company limits on a leave type are not included.

• Scope: group.
• include: none. Content: none. Run listing: no.

leave-allocations

Leave balances per employee, leave type and period. Manual balance adjustments are not part of this resource, so allocated plus carry_over minus taken can differ from the balance Hopshift shows.

• Scope: own company.
• include: none. Content: none. Run listing: no.

Payroll

payroll-items, payroll-documents, payslip-pdfs and intercompany-recharges serve rows of FINALIZED runs only. Follow the payroll rule to keep them right when runs are finalised, reopened or republished.

payroll-runs

Payroll runs of every status. A run's status says whether its payslips, documents, PDFs and recharges are served.

• Scope: own company (the run's company).
• include: notes adds notes (string).
• Content: none. Run listing: no.

payroll-items

Payslips of finalised runs, with their lines nested.

• Scope: the run is FINALIZED and its company is one of the key's.
• include: notes adds manual_notes (string) and no_sso_reason (string) to the payslip, and override_reason (string) and payslip_note (string) to each line.
• Content: none; the PDF is a payslip-pdfs row. Run listing: yes.
• Page size: at most 200 (default 200).

Each line:

payroll-documents

Government filings and the payroll export of finalised runs. Metadata only: the file is the content.

• Scope: the run exists, is FINALIZED and its company is one of the key's. Types PND1, PND1_PDF, SSO_1_10, SSO_1_10_PDF, SSO_SUBMISSION and PAYROLL_CSV. PAYSLIPS_ZIP is never listed.
• include: none.
• Content: the file; see Files for formats. Run listing: yes.

payslip-pdfs

Password-protected payslip PDFs of finalised runs. Metadata only: the file is the content.

A run has payslip PDFs only once it has been published from Hopshift. Runs finalised without being published, such as payroll imported from an earlier system, still have their payroll items and filings but no payslip PDFs.

• Scope: the run is FINALIZED in one of the key's companies, the PDF belongs to the run's active publication, and no later protection of the same payslip exists. A newer protection (for example after a birthday correction) arrives as a new row that replaces the earlier row with the same payroll_item_id.
• include: none.
• Content: the PDF as stored, AES-256 protected with the employee's birthday as DDMMYYYY (Gregorian year). 404 when there is no PDF. Run listing: yes.

pay-items

Each company's pay components: what payslip lines, employee pay items and schedules point at.

• Scope: own company.
• include: none. Content: none. Run listing: no.

pay-item-definitions

The group's canonical pay components. Company pay items sharing a definition are the same component across companies.

• Scope: group.
• include: none. Content: none. Run listing: no.

Fields: id plus the same fields as pay-items from code to updated_at (no company_id and no group_pay_item_definition_id).

employee-pay-items

Recurring pay components set on an employee.

• Scope: through the employee.
• include: notes adds notes (string).
• Content: none. Run listing: no.

employee-pay-schedules

Planned monthly amounts of a pay component for an employee. Imported incentives live here.

• Scope: through the employee.
• include: notes adds note (string).
• Content: none. Run listing: no.

meal-allowance-policies

Meal allowance rules: a group default (company_id null) and company overrides. An enrolled employee's policy is their company's override, else the group default.

• Scope: the group default reaches every key of the group; a company override reaches keys covering that company.
• include: notes adds description (string).
• Content: none. Run listing: no.

meal-allowance-enrollments

Which employees receive meal allowance. The policy is resolved by company, not stored here.

• Scope: own company.
• include: none. Content: none. Run listing: no.

intercompany-assignments

An employee of one company (source) working for another (host), with how the cost is recharged.

• Scope: either company: the key receives the row when the source or the host company is one of its companies.
• include: notes adds notes (string).
• Content: none. Run listing: no.

intercompany-recharges

What a host company owes the source company for one finalised payroll run, with lines per employee.

• Scope: the recharge is in the key's group, the source or the host company is one of the key's companies, the run is FINALIZED, and the recharge belongs to the run's current publication. A key without the source company gets payroll_run_id null; see the host-company limitation.
• include: notes adds notes (string), settlement_reference (string) and dispute_reason (string) to the recharge, and notes (string) to each line.
• Content: none. Run listing: yes.

Each line:

tax-declarations

Employees' yearly tax allowance and deduction declarations. Amounts only: no dependant names or ids.

• Scope: own company.
• include: notes adds notes (string).
• Content: none. Run listing: no.

History

audit-events

Hopshift's audit log, redacted. It covers only some changes, much of it imports and repairs; the per-record histories are clock-record-history, leave-request-history, employee-events and salary-adjustments.

• Scope: the audited record's company, resolved when the row is read, for these entity types: employee/Employee, shift/Shift (deleted shifts too), ClockRecord, ClockSession, AttendanceCorrectionRequest/attendance_correction, EmployeeLeaveAllocation, EmployeeLeaveGrant, UserEmailChangeRequest, PayrollRun, PayrollItem/payroll_item. Rows about the group's API keys, MCP keys, MCP connections and MCP operations (ApiKey, McpKey, McpOAuthGrant, McpOperation) have no company and reach only whole-group keys. Rows of any other type, and rows whose record no longer exists, reach no key.
• include:
  • notes adds reason (string, the actor's) and keeps free text inside values.
  • values adds values (object { "before": ..., "after": ... }, the recorded values). Without notes, every key that holds free text (notes, reasons, descriptions, comments, remarks, wouldRehire) is removed from them at any depth. values is null when the row recorded no values (its changed_fields is then empty) or when personal evidence hides it.
  • Both are null when the employee the row is about belongs to a company outside the key's companies or can no longer be found, and on payroll run and payslip rows whose run is not currently FINALIZED.
• Content: none. Run listing: no.