This version is in beta - expect some breaking changes.

National Insurance API

Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production Yes
Production base URL https://api.service.hmrc.gov.uk

Overview

This API retrieves an annual summary of an individual taxpayer's class 1 total earnings and class 2 National Insurance contributions due for a given tax year.

Its primary use is for the calculation of a self-employed taxpayer's National Insurance liability within the Self Assessment tax calculation.

Data availability

Data is available for taxpayers who, in the given tax year, have:

  • self-employment income
  • self-employment and employment income

Class 1 NICable earnings data is not available until Class 1 NICs reconciliation is complete. This starts in May and is usually complete by the end of August. Before reconciliation, Class 1 NICable earnings is returned as £0.00.

Class 2 NI contributions data should be available immediately at the end of the relevant tax year. However it can change after that date due to Class 1 NICs reconciliation or if we receive late changes from the taxpayer.

Find out more about National Insurance.

Authorisation

The endpoint in this API is user-restricted. Your users must grant authority for your software to access it by signing in to their HMRC online 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 their 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).

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 on versioning.

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

You can use the sandbox environment to test this API.

It supports stateful behaviour. You can set up test data for this API using the National Insurance Test Support API.

Skip to main content

Endpoints

/national-insurance/sa/{utr}/annual-summary/{taxYear}

Get National Insurance annual summary
GET

Fetches an individual’s National Insurance contributions for the given tax year.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the read:national-insurance scope.

Path parameters

Name Description
utr
string
required

The 10 digit self-assessment UTR for the individual.

For example: 2234567890

taxYear
string
required

The tax year for the National Insurance Contribution being retrieved.

Tax year in the format YYYY-YY

For example: 2014-15

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.1+json
Authorization
required
 An OAuth 2.0 Bearer Token with the read:national-insurance scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

{
      "class1":{
            "totalNICableEarnings": 10.00
      },
      "class2":{
            "totalDue": 20.00
       },
       "maxNICsReached": false
}

Name Description
class1
object
required
totalNICableEarnings
number
required

Total Class 1 earnings subject to National Insurance contributions between the Primary Threshold and the Upper Earnings Limit

For example: 10.00

class2
object
required
totalDue
number
required

Total Class 2 National Insurance contributions due

For example: 20.00

maxNICsReached
boolean
required

A flag indicating whether the maximum National Insurance contributions has been reached

For example: false

Error scenarios

Scenario HTTP status Code

Invalid UTR

400 (Bad Request)

SA_UTR_INVALID

Invalid tax year

400 (Bad Request)

TAX_YEAR_INVALID

Data not available for given UTR and tax year (see the data availability section for more details)

404 (Not Found)

NOT_FOUND

User not authorised to access data for given UTR

401 (Unauthorized)

UNAUTHORIZED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section

Skip to main content

Is this page not working properly? (opens in new tab)