RTI filing API
For payroll, HR and practice software. Version 1.
What it does
Your app works out an employer's payroll. It sends PactTax the pay run's figures, or the month's EPS figures, through PactTax's public API. PactTax keeps them as the business's own payroll records, builds the Full Payment Submission or Employer Payment Summary with its own RTI software, checks it against HMRC's schemas and business rules, and files it to HMRC under PactTax's vendor ID. PactTax does not take FPS or EPS documents built elsewhere: send the figures, and attest that they are the employer's own (attestation: true). Where the business keeps its books in PactTax, the pay run's wages journal goes into them too.
The authority your app needs
Ask for the rti:file scope, with payroll:read if you want to read the business's payroll too. Only the business's owner can grant rti:file. It is a standing authority: once granted, your app files without anyone confirming each run. The owner sees it in their connected apps, with what it has filed, and can withdraw it at any time, which stops your tokens at once. Every filing is in the business's audit trail and filing history with your app's name, and the owner is emailed HMRC's answer to each.
Endpoints
| Method | Path | What it is for |
|---|---|---|
| POST | /v1/businesses/{businessId}/rti/fps | A pay run as FPS data: who was paid, the payment, the year to date, starters and leavers. |
| POST | /v1/businesses/{businessId}/rti/eps | EPS figures for a tax month: amounts recovered, the Employment Allowance, the levy, no payment, the year's end. |
| GET | /v1/businesses/{businessId}/rti/submissions | Your app's submissions for the business, newest first. |
| GET | /v1/businesses/{businessId}/rti/submissions/{submissionId} | One submission: its status, HMRC's answer, the IRmark sent and the one on HMRC's receipt. |
| GET | /v1/businesses/{businessId}/rti/usage | What your app has filed for the business, by status. |
Every field, with its format, is in the OpenAPI document at /v1/openapi.json under the RTI tag, and in the PactTax SDKs for TypeScript and Python. Amounts are whole pence; dates are YYYY-MM-DD. An FPS holds up to 100 employees: send a larger payroll as several FPS for the same payday, each with its own reference.
The year to date
Send each employee's year to date as HMRC should hold it after this payment, with National Insurance by category letter. On your first run for an employee, PactTax keeps whatever came before as their year to date brought forward. After that, what PactTax holds plus this payment must equal the year to date you send, or the run is refused and nothing is kept. To correct an earlier period in the year, send the corrected year to date with correctsEarlierPeriods: true; PactTax records the correction in the audit trail.
Irregular pay, pay after leaving and strikes
Three of the FPS's indicators can be set on an employee, as HMRC's RTI data item guide 2026 to 2027 describes them. irregularPaymentPattern: true (IrrEmp, data item 40A) is for someone still employed who is paid irregularly, such as casual or seasonal staff, or who will not be paid for three months or more; send it on every FPS while it applies, and never with a leaver. paymentAfterLeaving: true (PmtAfterLeaving, data item 51) is for a payment after the leaving date was reported or the P45 given: send the original leaver.leavingDate with it, before payday, and tax the payment at 0T (S0T, C0T) with week1Month1: true. onStrike: true (OnStrike, data item 152) says the pay in this period was reduced by a strike. HMRC asks software not to complete Unpaid absence (data item 153) at present, so unpaidAbsence is refused.
Pay after statutory deductions
HMRC needs pay after statutory deductions (PayAfterStatDedns, data item 59) for every employee on every FPS. Send it as payment.payAfterStatutoryDeductionsMinor, in whole pence: the employee's net pay after tax, National Insurance and student and postgraduate loans, with any payrolled benefits, but without payments free of tax and National Insurance or deductions from net pay. If you leave it out, PactTax works it out as taxable pay less tax, employee National Insurance and loans. That is only right when all of the taxable pay was paid or is payrolled benefits, so send it yourself if you report a notional payment. If taxable pay is more than grossPayMinor, the run is refused until you send it.
The books
If the business keeps its books in PactTax, PactTax updates them too. When it takes a pay run, it posts the wages journal to the business's ledger before filing the FPS, the same journal as its own payroll posts: gross pay, employer National Insurance and pension as costs, and PAYE, National Insurance, student loans, pension and net pay as owed. The journal is marked as sent by your app in the business's audit trail. A pay run sent again under the same reference withdraws the earlier one and reverses its journal first, and a pay run refused before it is sent has its journal reversed. Closed books never stop the filing: HMRC's deadline comes first. If the business's books are closed for the payday, PactTax files the FPS and posts the journal on the first day the books are open, the way corrections are posted, and tells the business; once the period with the payday is opened again, the journal moves to the payday. The submission's books says what happened and the day the journal is dated (on): posted, deferred, not_kept, failed (nothing was filed: send it again) or reversed.
Never twice
Give every submission your own reference and send an Idempotency-Key header, as with every write. The same reference with the same figures returns the submission already made and files nothing again, however long after; with other figures it is refused. A submission PactTax refused before sending, or one HMRC did not accept or could not be reached for, may be sent again under the same reference with a new Idempotency-Key.
Test, sandbox and live
A sandbox business runs every check, HMRC's schemas and business rules included, and sends nothing: the submission comes back checked. In PactTax's test environment, filings go to HMRC's External Test Service. In production they go to HMRC's live service, once the employer has switched RTI filing on in PactTax, under the Government Gateway user ID and password you send with the submission (gatewayUserId, gatewayPassword). PactTax uses them for that one send and never keeps, logs or records them.
HMRC's answer
HMRC usually answers within minutes. Ask for the submission's status, or subscribe a webhook to rti_submission.accepted, rti_submission.rejected and rti_submission.needs_attention, which go only to the app that sent the submission. Each carries HMRC's reasons, the IRmark PactTax sent and, once accepted, the IRmark on HMRC's receipt. Every refusal says what is wrong, every problem at once, in problems.
Limits
The API's usual rate limit applies to every request, with its RateLimit headers. On top, an app may send 60 RTI submissions an hour for one business.