Pillar 2 API API
| REST | |
| 1.0 - controlled beta | |
| 29 May 2026 | |
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Production base URL | https://api.service.hmrc.gov.uk |
Overview
Pillar 2 charging mechanisms were introduced by the Organisation for Economic Cooperation and Development (OECD) to ensure Multinational Enterprises (MNEs) with a turnover of €750m or more are subject to a minimum Effective Tax Rate (ETR) of 15%.
The Pillar 2 API allows developers to
- submit a UK Tax Return (UKTR)
- amend a UK Tax Return
- submit a Below-Threshold Notification (BTN)
- return obligation and submission details for a specified accounting period
- submit an Overseas Return Notification (ORN)
- amend a submitted ORN
- retrieve the details of a submitted ORN
The Pillar 2 API Service Guide contains further information on integrating with the API, including a glossary of terms and acronyms relating to the Pillar 2 API. The Pillar 2 API Roadmap contains information on the Pillar 2 API release schedule.
Errors
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.
Testing
API testing is performed in our sandbox environment. Once you have registered for an account, you can conduct your own testing. The Pillar 2 API belongs to the “Corporation Tax” category.
Work through the instructions on the getting started page to create an application, then locate and subscribe to the Pillar 2 API.
Important: The Pillar 2 ID must be included in the request header or an error will be returned when the request is sent.
The next steps are outlined on the Open API Specification (OAS) page under “setup”. Access to the OAS page is currently restricted, so please use the link in the “Endpoints” section to contact support and submit an access request.
- Create a test user with a Pillar 2 subscription.
- Create a bearer token for the test user.
- Set up a test organisation.
- Run a Submit UK Tax Return request.
The Pillar 2 API Service Guide contains more detailed information on testing for each endpoint.
If you have a specific testing need that is not supported in the sandbox, please contact our support team.
Versioning
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 information on API versioning.
Endpoints
| Version | Environments | Endpoints |
|---|---|---|
|
Version 1.0 - beta
(opens in new tab) |
Sandbox and Production | Sign in to request access |