Work out your take-home pay
Income tax, National Insurance and net pay for any UK salary, 2026-27.
Around 30.3 million people are paid through PAYE Real Time Information each month in the UK, and every one of those payments carries a legal duty to report earnings and deductions to HMRC on or before payday [1] [2]. A payroll REST API is the software layer that turns that legal obligation into a set of predictable HTTP calls, so another platform can run compliant UK payroll without building the tax logic itself.
This article is written for developers and product teams. It explains what a payroll REST API does, the HMRC machinery it has to satisfy, how authentication and idempotency keep the integration safe, and how a full payrun flows through a set of endpoints from employee creation to Real Time Information submission.
It also draws the line between a data integration API and an embeddable payroll engine, because the two look similar on a slide and behave very differently in production. The embedded payroll category has grown quickly, with market estimates putting it at roughly $8.2 billion in value and a compound annual growth rate above 21% through the early 2030s, which is why more HR, ERP and accounting platforms are choosing to call a payroll API rather than write their own [3].
Key takeaways
- A payroll REST API exposes payroll operations, employee setup, payrun calculation and HMRC filing, as standard HTTP endpoints returning JSON.
- Every UK payroll API must send Real Time Information to HMRC, using the Full Payment Submission and Employer Payment Summary [2].
- HMRC recognition is the market entry requirement for any software that files RTI, not an optional badge [4].
- HMRC's own APIs use OAuth 2.0 bearer tokens that expire after 4 hours and must be tested in a sandbox before production access [5].
- Idempotency keys and signed webhooks are the two patterns that stop a payroll integration from paying an employee twice.
What a payroll REST API actually does
A payroll REST API represents each part of the payroll process as a resource that a client application can create, read, update or query over HTTP. An employer is a resource, an employee is a resource, a pay schedule is a resource, and a payrun is a resource that ties them together for a given period. The calling platform sends structured requests, usually JSON, and the engine returns calculated results and filing status.
The value of the model is that the complex, changing part of UK payroll stays inside the engine. Tax bands, National Insurance thresholds, statutory pay rates and student loan plans all shift at least once a year, and the calling platform should never have to hard-code them. When the engine holds the HMRC specification, the client platform simply posts gross pay and receives net pay, tax, National Insurance and every statutory deduction in return, calculated to HMRC's published precision [6] [7].
REST fundamentals for payroll
REST maps payroll actions onto standard HTTP verbs. A POST creates an employee or triggers a payrun, a GET reads a payslip or a filing receipt, a PUT or PATCH updates a tax code, and a DELETE marks a record as removed. HMRC's own developer platform follows the same convention, describing most of its services as RESTful interfaces built on standard HTTP verbs [8].
Responses carry meaning in their status codes as well as their bodies. A well-designed payroll API returns a 201 when a payrun is created, a 422 when the submitted data fails validation (a missing National Insurance number, an invalid tax code), and a 409 when a request conflicts with an existing resource. This lets the calling platform branch its logic on the status line before it even parses the JSON, which matters when a single payrun can touch dozens of employees at once [8].
Why payroll fits the API model
Payroll is unusually well suited to an API because it is deterministic and rule-bound. Given the same inputs, gross pay, tax code, National Insurance category and year-to-date figures, the output is fixed by HMRC's specification. That determinism is what allows an engine to guarantee the same result on every call, and it is why a platform can trust a payroll API to be the single source of truth for a figure like employer National Insurance, charged at 15% on earnings above the £5,000 Secondary Threshold for the 2026-27 tax year [7].
The second reason is regulatory. Because payroll reporting is mandatory and time-bound, the reporting step is not a nice-to-have feature but a core function that must fire on every payrun [2]. An API that treats HMRC filing as a first-class operation, rather than an export the user runs later, removes the most common source of employer penalties. Moonworkers exposes exactly this through its HMRC-recognised payroll API, where the RTI submission is part of the payrun call rather than a separate manual step.
The HMRC layer every UK payroll API must handle
No UK payroll API is complete without the HMRC integration, because calculating pay correctly is only half the job. The other half is telling HMRC what was paid, when, and to whom, in the exact format the Real Time Information specification demands [9].
RTI submissions: FPS and EPS
Real Time Information rests on two core submissions. The Full Payment Submission (FPS) reports each employee's pay and deductions and must reach HMRC on or before the day the employee is paid [2]. The Employer Payment Summary (EPS) reports adjustments that the FPS cannot carry, such as statutory pay recovery, the Employment Allowance, or a month in which no employees were paid [10].
The distinction matters at the API level because the two submissions fire under different conditions. An FPS is generated by a payrun; an EPS is generated by a reporting event that may have no payrun at all. Where an employer pays a worker below the level at which tax and National Insurance are due, an FPS is still required, but where no employee is paid in a tax month, only an EPS should be sent, using the 'No Payment for Period' indicator [10]. A payroll API has to model both paths so the calling platform never sends the wrong submission type.
HMRC recognition and the Developer Hub
Software that files RTI must be recognised by HMRC. Recognition confirms that a product meets HMRC's specifications for sending Full Payment Submissions, Employer Payment Summaries and other RTI messages, and recognised products are listed on the GOV.UK register of payroll software [4] [11]. Developers apply to the Software Developer Support Team, and HMRC aims to respond within 6 weeks [4].
The recognition step is why HMRC operates a Developer Hub and publishes RIM artefacts, data item guides and valid XML samples for each tax year [12]. HMRC has also stated that its wider strategy is to release APIs with richer capabilities to encourage third-party innovation, building on the way Real Time Information itself was delivered through close work with software developers [13]. For a platform embedding payroll, the practical point is that HMRC recognition is a baseline any serious engine already holds, so the buying decision turns on developer experience, not on the badge.
Authentication and security on a payroll REST API
Payroll data is among the most sensitive a business holds, combining salary, National Insurance numbers and bank details. Authentication on a payroll REST API therefore follows the same standards HMRC applies to its own services, built on OAuth 2.0 [5].
OAuth 2.0 and token lifecycles
HMRC uses OAuth 2.0, issuing access tokens that an application presents as a bearer token on each request [5]. Those access tokens last 4 hours, after which the application must obtain a new one, and an application authenticates using its client_id and client_secret [14]. A payroll integration has to handle this lifecycle gracefully, refreshing tokens before they expire so a long-running payrun does not fail halfway through a batch.
Token scope is the second control. When an application requests a token, it specifies the scopes the token is granted for, which limits what the token can do even if it is intercepted [5]. A payroll API that mirrors this model lets a calling platform hold a narrowly scoped credential, so an integration that only needs to read payslips never holds a token that could trigger a payment.
Endpoint access levels
HMRC divides its endpoints into access types, each with its own authorisation process [5]. Application-restricted endpoints authenticate the application itself, using the client credentials grant, and suit server-to-server calls where no individual user is present [14]. User-restricted endpoints authenticate a named user and are used where a person must consent to the action being taken on their behalf [15].
The same split is useful inside a payroll engine. A scheduled payrun that runs overnight is an application-restricted action, while an accountant approving a client's payslips in a dashboard is a user-restricted one. Modelling both means a single payroll engine can serve automated back-office jobs and interactive approval workflows without a second integration. Before any of this reaches production, HMRC requires that an application is tested in the sandbox, using sandbox credentials against a separate base URL, and that test users are generated through the Create Test User API [16] [17].
Designing reliable payroll integrations
An intermittent bug in a content API shows a stale headline; an intermittent bug in a payroll API can pay someone twice or miss a filing deadline. Reliability is therefore a design requirement, not a refinement, and two patterns carry most of the load.
Idempotency and retries
Idempotency means that sending the same request more than once has the same effect as sending it once. In payroll this is the difference between a retried payrun creating one set of payments and creating two. The standard approach is an idempotency key: the client generates a unique key for an operation, the engine stores it, and any repeat request carrying the same key returns the original result instead of processing again [18].
Retries make idempotency necessary rather than optional. Networks time out, and a client that does not receive a response cannot know whether the payrun was created, so it retries. Without an idempotency key, that retry risks a duplicate payment; with one, it is safe [18]. A robust integration pairs idempotency with exponential backoff, spacing out retries so a transient outage does not turn into a storm of repeated calls [19].
Webhooks and event-driven payroll
Payroll is full of events that happen outside the calling platform's control. HMRC acknowledges a submission, a payrun finishes calculating, or a filing is rejected and needs correcting. Webhooks let the engine push these events to the calling platform as they happen, rather than forcing the platform to poll for status [20].
The same idempotency discipline applies on the receiving side. A webhook provider may deliver the same event more than once, so the consumer should treat the event identifier as an idempotency key and ignore duplicates [20]. Webhook payloads should also be verified with a signature so the consumer can confirm the message genuinely came from the engine and was not forged, which matters when the event might trigger a payment or a filing [18]. Developers building against these patterns can browse the endpoint and event definitions in the Moonworkers API documentation.
A typical payroll API workflow, end to end
The clearest way to see how the pieces fit is to follow a single monthly payrun through the API. Each step is a discrete call, and the sequence is the same whether the calling platform is an HR system, an ERP or a bureau dashboard.
The table below sets out the stages of a standard payrun and the resource each one acts on. The exact endpoint names vary between engines, but the shape of the flow is consistent across any HMRC-recognised API.
| Stage | Action | Resource | HMRC touchpoint |
|---|---|---|---|
| 1. Set up employer | Register the PAYE scheme details | Employer | PAYE and Accounts Office references |
| 2. Add employees | Create each worker with tax code and NI category | Employee | Starter details, P45 or starter checklist |
| 3. Define schedule | Set the pay frequency and pay date | Pay schedule | Payment date reported on the FPS |
| 4. Run payroll | Submit gross pay, receive calculated deductions | Payrun | PAYE, NI, student loans calculated |
| 5. Confirm payslips | Read the calculated results for approval | Payslip | Figures match HMRC precision |
| 6. File RTI | Send the Full Payment Submission | FPS | On or before payday |
| 7. Adjust | Send an Employer Payment Summary where needed | EPS | By 19th of the following month |
Each stage validates before it proceeds. If an employee is missing a National Insurance number or carries an invalid tax code, the payrun call returns a validation error rather than filing incorrect data with HMRC, because a correct FPS depends on correct employee records [2]. The student loan step follows HMRC's rules for the relevant plan, deducting 9% of earnings above the plan threshold and passing the figure through to the FPS [21]. An SME payroll platform built on this flow lets a growing business run the whole sequence without leaving its own system.
Integration API versus embeddable engine
The most important distinction for a product team choosing a payroll API is whether it is buying a data integration or a payroll engine, because the two solve different problems. An integration API connects an existing payroll product to the tools around it, letting a customer who already runs that payroll product sync data with, say, an accounting ledger. The payroll still lives in the host product, and the API only moves data in and out [3].
An embeddable engine inverts that. The API is the payroll product, and another platform calls it from inside its own interface so that the end user never sees the underlying payroll vendor. This is the model that lets an HR platform, an ERP or a bureau tool offer full UK payroll as a native feature, calculating PAYE and National Insurance and filing RTI, without building any of the tax logic itself [13]. Accountancy firms managing many client schemes use the same distinction, calling a multi-client payroll platform through one integration rather than logging into a separate tool per client. Reading the difference correctly at the evaluation stage saves a costly rebuild later, because a data integration cannot be upgraded into an engine.
Work out an employee's true cost before integrating
Before wiring a payroll API into a platform, a developer can see the shape of its output with the Moonworkers UK salary calculator, which applies the 2026-27 PAYE and National Insurance rules to any gross salary and returns the same figures the API produces on a payrun.
£ per month
e.g. 1257L, S1257L, BR, D0
S = Scotland · C = Wales · W1/M1 = non-cumulative
Enter a salary or hourly rate above
About this calculator
This calculator gives you a close estimate of your UK payroll deductions for 2026-27, using HMRC's exact percentage method. It covers the vast majority of employees on standard tax codes, but it won't match your payslip to the penny in every case. Edge cases it does not cover include in-year tax code changes, K-code carry-forwards, Week 53 adjustments, payrolled benefits in kind, and multi-employment NI deferral. Powered by the same engine as the Moonworkers Payroll API.
Frequently asked questions
Why might the result differ from my payslip?
This calculator uses your current gross pay and tax code to produce an estimate. Your employer may apply adjustments not covered here, such as mid-year tax code changes, K-code carry-forwards, or benefits in kind processed through payroll. For most employees on a standard tax code these differences are negligible.
What tax code should I enter?
Use the tax code shown on your most recent payslip or the PAYE Coding Notice (P2) from HMRC. If you're not sure, 1257L is the standard code for most employees resident in England, Wales, or Northern Ireland. Use S1257L for Scotland or C1257L for Wales if you pay Scottish or Welsh income tax.
Which NI category applies to me?
Most employees use Category A. Use M if you are under 21, H if you are an apprentice under 25, or C if you are over State Pension age. Your employer is responsible for assigning the correct category — if in doubt, check your payslip.
Which student loan plan am I on?
Your plan depends on when and where you studied. Plan 1 covers students who started before September 2012. Plan 2 is for English and Welsh students who started from September 2012 to July 2023. Plan 5 applies to English students who started from August 2023. Plan 4 covers Scottish students. You can check your plan at gov.uk or on your payslip.
What is the YTD cumulative PAYE mode?
HMRC's standard method calculates income tax on your total earnings to date each period, then subtracts tax already paid. If you're mid-year and want to see exactly what tax should be deducted in a specific period, expand the Year-to-date section and enter your running totals from previous periods only.
Conclusion
A payroll REST API succeeds or fails on two things at once: whether it calculates UK pay to HMRC's specification, and whether it files Real Time Information reliably on every payrun. The calculation is the deterministic part, fixed by published tax and National Insurance rules. The filing is the operational part, where OAuth token lifecycles, idempotency keys and signed webhooks decide whether the integration is safe to run unattended.
The market is moving towards embedding that whole capability rather than rebuilding it, which is why the distinction between a data integration and a payroll engine has become the decisive question for platform teams. As more HR, ERP and accounting products add UK payroll as a native feature, the engines that expose clean REST endpoints, honest error codes and self-serve developer access will be the ones those platforms reach for first.
Frequently asked questions
What is a payroll REST API?
A payroll REST API is a web service that exposes payroll operations, creating employees, running payroll, and filing HMRC submissions, as standard HTTP endpoints that return structured data such as JSON. It lets another software platform run UK payroll by making API calls, instead of building the tax calculations and HMRC reporting itself. The engine holds the changing rules for PAYE, National Insurance and statutory pay, so the calling platform posts gross pay and receives fully calculated results [6].
Does a payroll API need to be HMRC-recognised?
Yes. Any software that submits Real Time Information to HMRC must be recognised, which confirms it meets HMRC's specifications for sending the Full Payment Submission, Employer Payment Summary and other RTI messages [4]. Recognised products appear on the GOV.UK register of payroll software [11]. Recognition is best treated as the entry requirement for a serious UK payroll engine rather than a distinguishing feature, because every credible product holds it.
How is a payroll API authenticated?
HMRC's payroll-related APIs use OAuth 2.0, where an application presents an access token as a bearer token on each request, and those tokens expire after 4 hours [5] [14]. Endpoints are split into application-restricted access, for server-to-server calls, and user-restricted access, where a named user consents to the action [15]. A payroll integration has to refresh tokens before they lapse and request only the scopes it needs.
How does a payroll API avoid paying an employee twice?
The main safeguard is idempotency. The calling platform attaches a unique idempotency key to each payrun request, and the engine returns the original result for any repeat request carrying that key, so a network retry cannot create a duplicate payment [18]. Pairing idempotency keys with exponential backoff on retries, and verifying webhook signatures before acting on an event, closes the remaining gaps that would otherwise let a duplicate slip through [19].
