Payroll journals API overview

The Payroll journals API turns a finalised pay run into a balanced, double-entry accounting journal that you can post to your accounting system (for example Xero or Sage) or download as a CSV or PDF. You control the shape of the journal with a template: which nominal codes each pay element and control account posts to, how lines are analysed by department or cost centre, and how the journal is narrated, referenced, dated, and formatted for export. The same feature is available in the product — see the Payroll journals guide. All endpoints sit under the /v1/journal base path, relative to the environment base URLs documented on the API reference introduction.

​

Key concepts

• Journal template — the reusable definition of how a pay run becomes a journal. It holds the account-code composition, narration and reference formats, export presets, and formatting options. An organisation can keep more than one template (for example, a summary journal and a detailed one).
• Pay element mapping — within a template, maps a pay element (basic pay, overtime, bonus, employer pension, and so on) to the nominal code it posts to.
• Control account mapping — maps a control account (net pay, PAYE, employee and employer NI, pension, student loan, and other liabilities) to its nominal code.
• Split dimension — an optional analysis dimension sourced from employee data, such as department, a tag group, NI category letter, student loan plan, or director status. A dimension can also be sourced from a pay line’s own description, which drives its nominal account only (for example routing an expense reimbursement to the right expense code) without adding a tracking column. Split dimensions break each journal line down into tracking categories or account-code segments.
• Split value mapping — maps a single value of a split dimension (for example, the “Warehouse” department) to its tracking code or account segment.
• Journal — the journal produced for a specific pay run. Journals are versioned: rebuilding or reissuing a pay run’s journal creates a new version, and the full history is retained.
• Export — the rendered output of a journal in a chosen format (CSV or PDF), available as a direct download or a time-limited download link.

​

API structure

​

Journal templates

Create, retrieve, update, clone, and delete templates: POST /templates, GET /templates/{templateId}, PATCH /templates/{templateId}, POST /templates/{templateId}/clone. Preview a template against a pay run as structured data (POST /templates/{templateId}/preview), CSV, or PDF before you rely on it. Export a template’s definition with GET /templates/{templateId}/export and import it into another organisation with POST /templates/import, or import just its mappings. Every change is recorded in the template’s history (GET /templates/{templateId}/history).

​

Pay element mappings and control account mappings

Attach nominal codes to the pay elements and control accounts a template uses. Both are key-addressed collections under a template: list them (GET /templates/{templateId}/pay-element-mappings, GET /templates/{templateId}/control-account-mappings), and create, update, retrieve, or delete an individual mapping with PUT, GET, and DELETE on its key.

​

Split dimensions and split value mappings

Add analysis dimensions to a template with POST /templates/{templateId}/split-dimensions and map each of their values. Split dimensions are ordered by sequence; split values are addressed by the value key within a dimension, for example PUT /templates/{templateId}/split-dimensions/{sequence}/values/{splitValueKey}.

​

Journals

List the journals for an organisation with GET /journals, retrieve one with GET /journals/{journalId}, and get the latest journal (GET /journals/latest) or all versions (GET /journals/versions) for a given pay run. For a large pay run, pass includeLines=false on GET /journals/{journalId} to return the header on its own (totals, reconciliation, the by-nominal and by-department summaries, and the warning chips, all computed from the complete journal), then page through the lines with GET /journals/{journalId}/lines. Rebuild a pay run’s journal with POST /journals/rebuild or reissue it with POST /journals/reissue, and review a journal’s history with GET /journals/{journalId}/history. Download an export with GET /journals/{journalId}/exports/{format}, or request a time-limited download link from GET /journals/{journalId}/exports/{format}/download-url.

​

Organisation journal settings

Read and update the organisation-level export defaults that apply across journals: GET /org-journal-settings and PUT /org-journal-settings.

​

Export metadata

Reference data used to build templates, served under /export-options: export presets, date-format presets, narration and reference tokens for the template’s token builders, and the available account-code separators.

​

Typical workflow

1. Create a template with POST /templates and set its export presets, date format, narration, and reference. Use the export metadata endpoints to populate the available presets, tokens, and separators.
2. Map your pay elements and control accounts to nominal codes.
3. Optionally add split dimensions (for example, department) and map their values to tracking codes or account segments.
4. Preview the template against a pay run — as data, CSV, or PDF — and adjust the mappings until the journal balances the way you expect.
5. Finalise the pay run — see Running a pay run. A journal is generated for the pay run; retrieve the latest journal with GET /journals/latest, or list its versions.
6. Download the export, or fetch a download link, in the configured format.
7. Rebuild or reissue the journal if the template or the underlying pay data changed, then download the new version.

​

Notes and best practices

• Journals are immutable snapshots. To reflect a change, rebuild or reissue the pay run’s journal rather than editing an existing version — the previous version is retained in history.
• Preview before you finalise. The CSV and PDF preview endpoints render the exact output your accounting system will receive.
• GET /journals, GET /journals/{journalId}/lines, and GET /templates are paginated with pageSize and paginationToken. Follow the token until it is no longer returned, and read totals from the journal header (or the summary), never by adding up a single page of lines.

​

Authentication

Every request must carry a valid token in the X-Auth-Token header, and credentials with access to more than one organisation must also send X-Org-Id — see Authentication. Responses use the shared envelope described in Response format.