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

# API reference

> Automate UK payroll end to end — employees, pay runs, payslips, RTI, pensions, statutory pay, and billing — over a single REST API.

The Flow Payroll API lets you automate payroll management programmatically: configure pay runs, manage employees and clients, upload payroll data, calculate gross-to-net, generate payslips, and stay HMRC-compliant through RTI submissions.

The API follows REST principles, uses JSON for requests and responses, and wraps every response in a [consistent envelope](/api-reference/response-format).

<Note>
  Need a `client_id` / `client_secret`? See [Authentication](/api-reference/authentication). Want the whole surface in one file for Postman or Insomnia? See [Use in Postman](/api-reference/use-in-postman).
</Note>

## Base URLs

Each service is reached through the API gateway under a versioned path. The core Pay API lives at `/v1`; every other domain has its own `/v1/<service>` (or `/v2/<service>`) prefix.

| Environment | Base URL                             |
| ----------- | ------------------------------------ |
| Sandbox     | `https://api.sandbox.flowpayroll.ai` |
| Live        | `https://api.flowpayroll.ai`         |

<Warning>
  Always build and test against **sandbox** first. Sandbox data is isolated from live and safe to experiment with.
</Warning>

## API families

The reference is grouped by service. Each group below is generated directly from that service's OpenAPI specification.

<CardGroup cols={2}>
  <Card title="Authentication API" icon="key" href="/api-reference/authentication-api/overview">
    Discover the organisations your credentials can act on, and pick one per request with `X-Org-Id`.
  </Card>

  <Card title="Pay API" icon="money-check-dollar" href="/api-reference/pay-api/overview">
    The core of payroll: employees, payroll runs, the gross-to-net calculator, payslips, and RTI (FPS & EPS).
  </Card>

  <Card title="Statutory pay" icon="heart-pulse" href="/api-reference/statutory-pay/overview">
    Calculate and record SSP, SMP, SPP, ShPP, SAP and more, with average-earnings checks and reconciliation.
  </Card>

  <Card title="Court orders" icon="gavel" href="/api-reference/court-orders/overview">
    Attachment of earnings — CMS DEO, AEO, DEA, CTAEO and others — plus payees and protected-earnings handling.
  </Card>

  <Card title="Holiday & leave" icon="umbrella-beach" href="/api-reference/holiday/overview">
    Leave records, opening balances, accrual configuration, and average holiday-pay history.
  </Card>

  <Card title="Pensions" icon="piggy-bank" href="/api-reference/pensions-v2/overview">
    Auto-enrolment assessment, schemes, providers, groups, calculations, exports and enrolment letters.
  </Card>

  <Card title="Recurring line items" icon="repeat" href="/api-reference/recurring-line-items/overview">
    Recurring pay and deduction items, their periods, and skip/patch operations.
  </Card>

  <Card title="HMRC DPS" icon="inbox" href="/api-reference/hmrc-dps/overview">
    Retrieve and apply HMRC Data Provisioning Service notifications (tax codes, student loans, and more).
  </Card>

  <Card title="HMRC P-forms" icon="file-lines" href="/api-reference/hmrc-p-forms/overview">
    Generate statutory forms such as the P45.
  </Card>

  <Card title="Billing" icon="file-invoice" href="/api-reference/billing/overview">
    Clients, invoices, credit notes, finance settings, and accounting-provider sync.
  </Card>

  <Card title="Payment" icon="building-columns" href="/api-reference/payment/overview">
    Generate BACS payment files (Standard 18, Barclays, Allica) for completed pay runs, and manage payment configuration.
  </Card>

  <Card title="Payroll journals" icon="book-open" href="/api-reference/journal/overview">
    Turn finalised pay runs into accounting journals: templates, nominal and control-account mappings, split dimensions, and CSV/PDF exports.
  </Card>

  <Card title="Reports (Beta)" icon="chart-column" href="/api-reference/reports/overview">
    Query payroll data with a JSON report definition: datasets, synchronous runs, CSV/JSONL exports, and scheduled deliveries.
  </Card>
</CardGroup>

## A typical payroll run

<Steps>
  <Step title="Configure">
    Create a payroll configuration with `POST /payrollconfig` (pay frequency and settings).
  </Step>

  <Step title="Add people">
    Add employees with `POST /employee`, and clients with `POST /client` if you run payroll for multiple entities.
  </Step>

  <Step title="Upload pay data">
    Send pay and deduction lines with `POST /payroll/upload`.
  </Step>

  <Step title="Preview">
    Preview payslips at any time with `GET /payslip/data/{employeeId}/{year}/{period}` — even outside the configured frequency.
  </Step>

  <Step title="Lock & submit">
    Lock the period to generate final payslips, then submit the FPS to HMRC. Submit the EPS at month-end.
  </Step>
</Steps>

## Conventions

* **Organisation scoping** — every resource belongs to an organisation, which is derived from your credentials. You never pass an organisation ID in the request body.
* **IDs** — resources use ULID-based identifiers.
* **Dates** — ISO‑8601. Response metadata states the exact `dateFormat` and `dateTimeFormat` in use.
* **Pagination** — list endpoints are paginated; page through large result sets rather than requesting everything at once.

## Support

Stuck on an endpoint? Email [hello@flowpayroll.ai](mailto:hello@flowpayroll.ai).