How to use HMRC Self assessment APIs for Individuals

What are APIs?

HMRC have provided a method of obtaining information relevant to the completion of a Tax Return called Application Program Interfaces or APIs. This is the first part of their overall Digital transformation project known as Making Tax Digital. 

Not an Individual user?

The following article relates to the non-practice version of the software. If you are a practice please click here for help on using the APIs.

What data can be requested from HMRC?

This article will help you to use the HMRC Self assessment APIs to obtain information direct from HMRC. Please click here to find out what information you will receive from HMRC.

Prerequisites for using the Self assessment APIs

The following details must be completed to ensure that information can be obtained from HMRC for Tax Returns:

• UTR
• Each Return you prepare must be a current live Self Assessment case with HMRC. This means HMRC are expecting a Self Assessment Return. If there has been no Returns submitted previously then HMRC may have made them "inactive". you will be required to contact HMRC to change this status before using the APIs.  

Step 1 - Authorising TaxCalc to talk to HMRC

The first step is to authorise TaxCalc software. This is a process that effectively links TaxCalc to HMRC.

To authorise the software:

1. Open the current year Tax Return
2. Click on Set up Return.
3. Select the arrow button on the Fetch taxpayer data screen located at the foot of the window.

4. Click on the Fetch button  
5. You will be taken to the HMRC website to create an account using your current Gateway Credentials.  

Step 2: Fetching information from HMRC

Click on the Fetch button following the successful authorisation of TaxCalc.

The following screen will be displayed:

The data TaxCalc has retrieved from HMRC will be displayed in each of the relevant areas. The list on the left hand side will be displayed in bold where data is present.

TaxCalc stepped process will guide you through each of the screens displaying a summary of the data on the final screen:

Click on the Fetch button to have  the data shown within the Tax Return. Data within the Tax Return can be identified by the box being shown in green with the HMRC logo alongside it.   

What do I do if the data received from HMRC is incorrect?

It is recommended that you check the data being received from HMRC against documentation provided to you from the income provider such as your Employer or Pension provider before submitting your Tax Return to HMRC. If you consider the data to be incorrect then you can either:

• Not accept the data being provided when using the APIs by clicking on Cancel or
• Overwrite the data from within Tax Return production that you have fetched from HMRC

Understanding error messages

 Below is a list of the most common errors you may encounter while using the APIs: