> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay API overview

> Manage employees, payroll configurations, and pay runs — upload pay data, calculate gross to net, produce payslips, and submit RTI to HMRC.

The Pay API is the core of Flow Payroll. It covers the full payroll cycle: setting up your organisation and payroll configurations, managing employee records and their tax details, uploading pay data, locking pay runs, retrieving payslips, and submitting RTI (FPS and EPS) to HMRC. Use it when you integrate payroll processing itself — the other services in this reference (pensions, statutory pay, court orders, and so on) build on the data this API manages.

The Pay API sits at the `/v1` base path, directly under the gateway base URLs listed in the [API reference introduction](/api-reference/introduction). All endpoint paths on this page are relative to that base path.

## 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

Manage organisation information, HMRC settings, opening balances, year-to-date running balances, and PAYE liability, including recording the PAYE payments you make to HMRC. `GET /organisation/information` and `POST /organisation/hmrc/settings` are the starting points; organisation-wide working-pattern defaults live under `/organisation/working-pattern-defaults`. See the [organisation setup guide](/guides/setup/organisation-setup) for the product-side view.

### Pay elements

Create, read, update, and delete the pay elements available to your organisation under `/organisation/pay-element`. Payroll lines reference these definitions.

### Payroll configurations

Create and manage pay schedules with `POST /payrollconfig` and its companions. A configuration can carry its own working-pattern defaults that override the organisation default. The [pay run settings guide](/guides/setup/pay-run-settings) explains the equivalent product screens.

### Employees

Full lifecycle management of employee records: `POST /employees` to create, `GET /employees` to list with pagination, plus lookups by National Insurance number and payroll ID. Working patterns, working schedules, and SSP qualifying-day policies are managed per employee as effective-dated records. See [managing people](/guides/people/managing-people).

### Tax codes, NI, and loans

Maintain each employee's effective-dated tax codes and NI categories, update their NI number or payroll ID, and start or end student and postgraduate loans. `GET /employees/{employeeId}/effective-tax-info` returns the tax code and NI category in force on a given date.

### Starters and leavers

Set starter details with `PUT /employees/{employeeId}/starter`, and set or cancel leaver details individually or in bulk via `PUT /employees/leaver/bulk`. See the [onboarding](/guides/people/onboarding-employees) and [leavers](/guides/people/leavers) guides.

### Payroll runs and pay data

Upload pay data with `POST /payroll/line/{employeeId}`, attach supporting documents to lines, and set employee opening balances and payroll-config assignments. Create a run for a specific period, or use `POST /payroll/{payrollConfigId}/next` to create the next one in sequence, then finalise it with `POST /payroll/{payrollConfigId}/{year}/{period}/lock`. Listing endpoints return runs by tax year and the employees included in a run.

### Calculator

`POST /calculator/grosstonet` calculates gross-to-net values, including tax and NI, so you can preview figures before locking a run.

### Payslips

Retrieve payslips for a whole pay run, for an employee in a period, or for an employee across a date range. You can also set payslip metadata such as notes and a payment-date overwrite, and send payslip notification emails with `POST /notification/email/payslip/{payrollConfigId}/{year}/{period}`. See the [payslips guide](/guides/pay-runs/payslips).

### RTI

Trigger an FPS for a pay run with `POST /rti/fps/{payrollConfigId}/{taxYear}/{period}` and retrieve its details. Submit an EPS from monthly balances or manually, resubmit a manual EPS, and list submissions by tax year. See the [HMRC RTI guide](/guides/compliance/hmrc-rti).

### Year end

Finalise year-end for a payroll configuration with `POST /payroll/year-end/{taxYear}/{payrollConfigId}/finalise`, and read finalisations per configuration or across the organisation.

## 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](/guides/pay-runs/running-a-pay-run) 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.
* **EPS corrections** — a manual EPS can be resubmitted with `POST /rti/eps/{taxYear}/manual/{submissionId}/resubmit` if HMRC rejects it or the figures change.

## Authentication

Every request needs a bearer token in the `X-Auth-Token` header, and credentials with access to more than one organisation should also send `X-Org-Id` — see [Authentication](/api-reference/authentication). All responses use the shared envelope described in [Response format](/api-reference/response-format).