Knowledge Base
Knowledgebase Support HMRC Useful links
Knowledgebase home
Tax Return Production
Accounts Production
Practice Management
VAT Filer
Anti-Money Laundering
Support home
Video Training Guides

Hot Topics
SimpleStep Guides
Release Notes
Known Issues

Service Status
Useful Links
What is MTD? Support for Accountants Support for Business
HMRC's MTD Timeline
Digital Requirements
TaxCalc's MTD Journey
MTD for Income Tax
MTD for Corporation Tax
MTD for Income Tax
MTD for Corporation Tax
Step-by-step Guide

TaxCalc Blog

News and events from TaxCalc

Greg Case (1)
19 January 2016

HMRC's New APIs – How They Work in TaxCalc 2016

Hi there. I’m Greg Case and I’m TaxCalc’s Head of Product Development. I’ve recently been reviewing HMRC’s progress with the implementation of their new Application Program Interfaces (APIs) and how we’re going to incorporate this into the forthcoming 2016 version of our software.

In a nutshell it will give TaxCalc the ability to gather information that HMRC hold about a taxpayer and, in time, even update it in real time and outside of the tax return itself.

But only if you want it to. To do this, you need to give your TaxCalc software permission to work with HMRC’s APIs. TaxCalc can’t access any information unless you allow it to.

In this article, we’ll look at how it works.

What can the APIs do?

Completing a return is going to become a more interactive experience and your TaxCalc software is going to be able to interact with HMRC on more levels than ever before such as:

  • Prepopulate parts of the Self Assessment return
  • Prepopulate Class 1 and Class 2 National Insurance
  • Check eligibility to the transfer of the Marriage Allowance

The first two will allow TaxCalc to automatically populate information such as Employer name, PAYE reference, income and tax paid and P11D benefits. Pension and benefits received will be available as well as liabilities to Class 1 and 2 National Insurance.

The Marriage Allowance API should allow TaxCalc to check eligibility to claim this new election and also to actually make the election to give the allowance to a spouse from within TaxCalc. So this could be the first truly interactive API, taking information from HMRC but also sending it to them, in advance of actually submitting a return.

Now, HMRC have never provided software with the capability of reading off information from their systems. This is all new and to do any of this, you will need to give your software permission.

Collecting information

Currently in TaxCalc, whether you are an individual, business or accountant customer, there are places where you can store your Government Gateway filing credentials (your 12 character account and password).

These screens are used only for filing. When it comes to using any of the new APIs, we will have new screens to do this.

In time the online filing mechanism should all be rolled into the same set of APIs but for now online filing itself, and the new APIs, will be separated.

For our accountants, there will be a central means of granting permissions in the Administration module so you will have control over who in your firm can access client information.

For other customers, you will be able to authorise TaxCalc within any specific tax return.

Throughout the tax return we will place new ‘Fetch’ buttons. These buttons do what they say on the tin: they will fetch information (if present) from HMRC for certain areas of the tax return. For example, if you’re in the Employment section and you want to ‘Fetch’ something then it can access the API, get the employment information about the taxpayer and use it to populate the return. If you haven’t given TaxCalc permission to access them then you will be asked to do that first.

Getting permission from HMRC

To authorise TaxCalc, you need to connect to the HMRC website itself. But don’t worry, we can let you do this from within TaxCalc. HMRC are still finalising this process but it should look something like this:


It’s just as secure as the HMRC website and you’ll need to use your Government Gateway login.

You’ll see that it’s a TaxCalc window but inside is the HMRC website and it is styled with HMRC’s branding rather than our own. When you have entered your Government Gateway credentials, you should see a page that tells you want you’re allowing TaxCalc to do and which information it can collect on your behalf. If you’re happy with what you see, you can simply click a button to accept the authorisation and that’s it! You’ve authorised TaxCalc to ‘fetch’ the information as and when you ask it to.

What happens if I don’t give permission?

Don’t worry, you’ll still be able to complete your returns. For the time being these APIs are meant to save you time and let you check things in order to make a more informed decision and spot any problems before they arise. You don’t have to use it but TaxCalc will only be fetching data when you ask it to, so it makes sense.

HMRC are going to be adding more and more APIs over time so you may find that new APIs will require you to re-authorise TaxCalc to access the new APIs from time to time. Ultimately, it will be up to you if you want to make use of them.

Who am I giving permission to?

In conjunction with HMRC, we conducted some user testing and were very grateful for the time given by six of our customers.

One of the key questions that testers asked was “who am I giving permission to?”. Was it the software or Acorah Software Products Limited, the company that makes TaxCalc?

I can confirm that it’s the software that’s installed on your computer that receives the permission. We (the company) won’t be handling your data at all.

How long will my permission last?

Currently, we are expecting the permission for any particular API (or APIs) to last for at least one calendar year. We have suggested to HMRC that it lasts longer than this, possibly as long as 18 months.

We will be able to show you how long it lasts so that you know when you will be asked to re-authorise it.

What will happen in the long run?

As I mentioned above, the old APIs that you use to file your tax return will, ultimately, be retired and a new API will be provided under the current model. As such, you’ll be providing your TaxCalc software with permission to download and upload data to HMRC.

Other APIs on HMRC’s roadmap that will come in time will include VAT and EC Sales List as well as Payroll and Corporation Tax. More on this as and when I hear it.

We very much have HMRC’s ear on what APIs are going to be useful in the future and they’re involving us more than ever, so if you have any ideas or other comments on this, please leave them in the comments section below or email

A final word from HMRC

HMRC are working hard on APIs. You might like to read a recent blog post from HMRC’s Head of Design and Delivery for the API Programme.

Print this article
9 people like this

Share this article:


CommentLog in
You must log in to comment.

Tony Margaritelli (7 years ago)

Thanks for this update. It explains a lot about APIs, how they will work in reality and just as importantly the whole permission issue. I actually now have a picture of the new system in my head where before I only had questions - Tony Margaritelli Chair ICPA
Comments are subject to house rules

How to subscribe

Get the TaxCalc news as soon as we publish it!

To sign up, please log in or create an account.

Log in

How to comment

If you already have a TaxCalc account, you can comment on any articles written here.

To avoid using your actual name, you can create a special ID. Just log in and visit your customer account to create it.

Create your ID