This version is in beta - expect some breaking changes.
Individual PAYE API
|Available in Sandbox||Yes|
|Sandbox base URL||https://test-api.service.hmrc.gov.uk|
|Available in Production||Yes - private trial|
|Production base URL||https://api.service.hmrc.gov.uk|
Use this API to get Paye As You Earn (PAYE) information about an individual, including:
- employments - including income, tax, student loan deductions and company benefits
- private pensions - including income and tax
- State Pension - including regular payments and lump sums
- tax-free allowances
- taxable social security benefits - including Jobseeker’s Allowance, Employment and Support Allowance and Incapacity Benefit
You can find the changelog in the individuals-paye GitHub wiki.
API status and roadmap
This API is currently in beta - expect some breaking changes.
This API is currently in a low-volume private trial. You can use the sandbox service, however the production service is now ring-fenced for a select amount of users.
We will make the production service public once the trial is complete. We do not have a forecast date for this yet.
This API will eventually replace the following APIs (from Phase 1):
- Bug fixes- residual work from delivery of Phase 1
- Amalgamation of the four Individual APIs to have Individuals PAYE API, National Insurance and, Marriage Allowance
Roadmap for Phase 3:
- Data quality improvements identified through Phase 1 and Phase 2 (that do not impact the stability of the APIs for SA peak)
- taxable social security benefits and state pension lump sum - pay and tax data not populated
- some private pensions might still be coming through as employments
- State Pension - first year figure is a weekly amount, not an annual amount
- increase capacity to support full production volumes
- untaxed interest, including bank and building society interest
- UK dividends
- tax refunded or set off
- end user guidance on GOV.UK
- end-to-end service guide
- residency status - for example Scotland, Wales non UK
Backlog items currently labelled as Phase 4 on our Roadmap. The caveat here is that these items will need user research and / or business requirements to understand the user needs and priority before they are brought in to scope for development
- current year data
- payment level data (instead of annual summary)
- student loan type
- child benefit - higher income charge
- taxed interest
- foreign dividends
- tax collected in previous year tax code
- underpaid tax and debts
- taxable profits
If you would like to suggest other features or discuss priorities, contact us.
Data availability and status
You can get data for the previous four tax years (but see restrictions for agents in the Authorisation section). You cannot get data for the current tax year or for earlier tax years.
Further details follow on the availability of specific data items.
Employment and private pension payments and deductions
We receive employment and private pension payments and deductions data from employers and pension providers via a Full Payment Submission, usually on or before each payment date.
You can get data for the previous tax year as soon as the tax year has ended, that is from April 6th. However, the data can change after that if the employer sends us an Earlier Year Update.
The data does not include:
- a breakdown of any Earlier Year Updates
- any corrections made by us after year end (although this is rare)
- whether or not we have reconciled the account and completed the tax calculation
Prior to this, you get our forecast based on the previous year’s figures, including a flag to tell you that it’s a forecast.
We receive State Pension data (regular payments and lump sums) from the Department of Work and Pensions.
You can get State Pension regular payment data for the previous tax year as soon as the tax year has ended, that is from April 6th.
You can usually get State Pension lump sum data by the end of June.
We receive tax-free allowances data directly from individuals. They can report them at any time for future, current or previous tax years.
Even though individuals report tax-free allowances against a specific employment, we do not record them that way, which is why the API returns them separately from employments.
Taxable social security benefits
We receive taxable social security benefits data from the Department for Work and Pensions.
You can usually get taxable social security benefits data for the previous tax year by the end of June.
You can get more details on the various PAYE processes in our PAYE Manual.
The information provided by this API is based on information we receive from external parties - individuals, their employers or pensions providers, and the Department of Work and Pensions.
You should advise your users to check the information before using it.
The endpoint in this API is user-restricted. Your users must grant authority for your software to access it by signing in to their Government Gateway account.
The API supports individual and agent users. Note that:
- Individual users can only access their own information.
- Agent users can only access their own clients’ data.
The following options are supported for agents:
Option 1: Agent services account
If the agent uses an agent services account, they can access:
- new clients, who have authorised the agent to view their PAYE income record via the agent services account
- existing 64-8 clients who they have linked to their agent services account (restricted to 2 years’ history)
Option 2: HMRC online services for agents account
If the agent uses an HMRC online services for agents account which is enrolled for Self Assessment for Agents, they will be able to access their existing 64-8 clients (restricted to 2 years’ history).
The API supports a single scope -
read:individual-paye. It cannot be used with the same scopes as the
Individual Income or
APIs, so if you are migrating from these APIs, you will need to send your users back through the grant authority process.
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.