Pay API overview

​

Key concepts

• Payroll configuration — a pay schedule that employees are assigned to. Every pay run belongs to exactly one payroll configuration, and an organisation can run several in parallel.
• Pay run — the processing of one pay period, identified by payroll configuration, tax year, and period. Locking a run finalises it.
• Pay element — an organisation-level definition of a pay item type (for example basic pay or overtime) that uploaded pay data refers to.
• Payroll line — a single pay item uploaded for an employee for a pay date. Payroll lines are the input to a pay run’s gross-to-net calculation.
• Payslip — the per-employee output of a pay run, retrievable individually, by pay run, or across a date range.
• Effective-dated records — tax codes, NI categories, working patterns, and SSP qualifying-day policies are stored with effective dates, so a change applies from a given date without losing history.
• FPS — the Full Payment Submission sent to HMRC for a specific pay run.
• EPS — the Employer Payment Summary for a tax month, submitted from monthly balances or manually.
• Year-end finalisation — closes a tax year for a payroll configuration once its final pay run is complete.

​

API structure

​

Organisation

​

Pay elements

​

Payroll configurations

​

Employees

​

Tax codes, NI, and loans

​

Starters and leavers

​

Payroll runs and pay data

​

Calculator

​

Payslips

​

Reading pension on a payslip

• forPeriod.pension (and the year-to-date and employment-to-date equivalents) is the member’s total pension movement for the slice: contributions deducted, including additional voluntary contributions, less any opt-out refunds paid back.
• summaryItems carries one row per pension contribution, each classified by pensionLineType, for organisations using itemised pension contributions.

const CONTRIBUTION_TYPES = new Set([
  'Contribution',
  'RecurringAdditionalVoluntaryContribution',
  'AdditionalVoluntaryContribution',
])

const pensionRows = payslip.summaryItems.filter(item =>
  CONTRIBUTION_TYPES.has(item.pensionLineType)
)
const refundRows = payslip.summaryItems.filter(
  item => item.pensionLineType === 'OptOutRefund'
)

// Itemised: total the rows and ignore forPeriod.pension.
// Aggregate: there are no rows, so forPeriod.pension is the only source.
const employeePension = pensionRows.length
  ? pensionRows.reduce((total, item) => total + item.amount, 0) -
    refundRows.reduce((total, item) => total + item.amount, 0)
  : payslip.forPeriod.pension

• pensionEmployerContribution is the employer contribution attributable to that line. It is already inside forPeriod.employerPension, so it is display metadata, not a separate cost.
• pensionMetadata records the context the row calculated under: the pension group, the contribution basis, the employer share, and a contributionSource saying whether the settings came from the group, a standing per-employee override, or an override for this pay run only.

​

RTI

​

Year end

​

Typical workflow

1. Set your organisation information and HMRC settings with POST /organisation/information and POST /organisation/hmrc/settings.
2. Create a payroll configuration with POST /payrollconfig and define your pay elements under /organisation/pay-element.
3. Add employees with POST /employees, then set their starter details, tax codes, and NI categories.
4. Upload each employee’s pay data for the period with POST /payroll/line/{employeeId}.
5. Preview the figures with POST /calculator/grosstonet and resolve any validation issues reported on upload.
6. Lock the run with POST /payroll/{payrollConfigId}/{year}/{period}/lock, then retrieve payslips for the run and email them to employees. The running a pay run guide covers the same flow in the product.
7. Submit the FPS for the run with POST /rti/fps/{payrollConfigId}/{taxYear}/{period}, and submit the EPS for each tax month from monthly balances.

​

Notes and best practices

• Pagination — GET /employees accepts pageSize (1–100) and paginationToken; pass the returned token to fetch the next page.
• Payroll line uploads — each request accepts up to 100 lines. Lines that fail validation are reported back, and every accepted line’s response includes a payrollDate: the date you supplied, or the next unlocked pay date if that date’s run is already locked.
• Locking — locking creates the pay run record in a locked state for that configuration, tax year, and period. Upload and correct pay data before you lock.
• FPS request body — POST /rti/fps/{payrollConfigId}/{taxYear}/{period} takes { "finalSubmissionDetails": { ... }, "lateReason": "..." }, both optional. lateReason is HMRC’s late reporting reason for an FPS sent after the payment date (codes A, B, C, D, F, G, H; the withdrawn code E is rejected) and is reported on every payment. Sending the final submission details object as the body itself is deprecated as input and stops being accepted on 15 January 2027; wrap it in finalSubmissionDetails. See Deprecations.
• EPS corrections — a manual EPS can be resubmitted with POST /rti/eps/{taxYear}/manual/{submissionId}/resubmit if HMRC rejects it or the figures change.
• Opening balances — the flat NI totals on openingBalanceDirector and the aggregate pension on openingBalance are deprecated as input and stop being accepted on 7 November 2026; send niBandResult and pensionContributionsByType instead. Both keep being returned on responses, so only what you send changes. See Deprecations.
• Salary — salary is deprecated as input on PUT and PATCH /employees/{employeeId}, and stops being accepted on those two operations on 20 December 2026; record changes with PUT /employees/{employeeId}/salary, which keeps an effective-dated history. POST /employees still accepts it as the starting salary, and it keeps being returned on every response as the amount in force today, so only what you send changes. See Deprecations.
• Pay schedule changes — payFrequency and paymentPeriodConfig can only be changed on a payroll configuration that has no pay runs. Once a run exists, of any status, PUT /payrollconfig/{payrollConfigId} refuses a change to either with a 409 and the token payroll_config_has_pay_runs. Everything else on the configuration stays editable, and re-sending the two fields unchanged is always accepted, so a full-body PUT that only renames the schedule still works. GET /payrollconfig/{payrollConfigId} returns hasPayRuns so you can show the fields as locked instead of waiting for the refusal; it is read-only and ignored if you send it back.
• Payslip PDFs — GET /payslip/data/{employeeId}/{year}/{period}/file returns the payslip as application/pdf (send Accept: application/pdf), with the file name in Content-Disposition. It is not password-protected; only the copy emailed to the employee is.
• Pension totals: take pension from the summaryItems rows or from forPeriod.pension, never from both. See reading pension on a payslip.

​

Authentication