How to use HMRC Self assessment APIs for practice

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 a practice?

The following article relates to users of the practice software. If you are an individual please click here for help on using the APIs.

What data can be requested from HMRC for Self assessments?

This article will help you to use the HMRC APIs to obtain self assessment 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
• 64-8 lodged with HMRC for each client
• The client 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 (with you as an agent) to HMRC. Please follow the steps below to authorise the software:

1. Select a client and open the current year tax return
2. Make sure you are in SimpleStep Mode
3. Click on Set up Return.
4. 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 where you will receive a 6 digit access code to connect the TaxCalc application to the HMRC website.  

Step 2: Fetching information from HMRC

Once you have authorised TaxCalc then 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's 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 by your client before submitting the 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: