Key Takeaways

• A comprehensive list/documentation of the UK's online tax system's RESTful and XML APIs for its developer hub can be found here.
• HM Revenue and Customs (HMRC) first launched its set of improved application programming interfaces (APIs) on September 1, 2015, as part of its digital strategy.

Introduction

1. API Overview

(i) Date of Launch

• HMRC, the UK government's payments and customs authority responsible for the collection and administration of taxes, first launched its set of improved application programming interfaces (APIs) on September 1, 2015, as part of its digital strategy.
• The department recognized the need to boost commercially available tax software following their growing preference among customers, particularly, businesses and agents, by releasing APIs with richer capabilities for software developers to leverage and innovative develop new and more sophisticated products.
• As of March 2018, HMRC had made six APIs available for software developers to leverage in creating new routes into its digital self-assessment taxation services, which are typically used to capture income tax from landlords, the self-employed, as well as people and businesses with income other than wages, pensions and savings, including individual income, individual benefits, individual employments, individual tax, marriage allowance, and national insurance.
• By the end of 2017, HMRC'S API platform had received over 100 million calls for data exchange and was receiving around a million API calls per day as of October 2018, with 99.99% availability. Additionally, their 2018/2019 annual report stated that HMRC had reached 368 million requests to their API platform enabling interaction between commercial software used by businesses and agents and themselves, hence reducing the need for customers to contact them.

(ii) Actions Available

• HMRC's developer hub supports both RESTful APIs and XML APIs. 
• The developer hub allows users of third party applications to learn about HMRC's RESTful API platform, access a detailed documentation of its API, integrate their applications with the APIs, and test them application in the sandbox.
• Additionally, particularly for XML software developers, the developer hub offers both an online test service/third party validation service (TPVS) and a downloadable offline testing tool/ local test service (LTS), a test-in-live option, and the option to apply for HMRC recognition for their application/software product.

• A comprehensive list/documentation of the UK's online tax system's RESTful and XML APIs for its Developer Hub can be found here.

• There is a wide range of actions available via the APIs including: authorization of agents to act on behalf of businesses or individuals, computation, valuation, and submission of repayment claims for items such as business rates and charities, various customs support functions, such as checking Economic Operators Registration and Identification (EORI) numbers and pulling notifications, listing and retrieval of business information, including income and expenditure summaries, among others.
• A more in depth discussion of the actions available via the APIs is provided below.

2. Functions

(i) Income Tax

• As part of HMRC's Making Tax Digital initiative, the department offers the following APIs regarding income tax, including their use:

• Agent Authorization API: allows tax agents to "request authorization to act on a client’s behalf for a specific Making Tax Digital (MTD) tax service and have the option to cancel the authorization request. The API also allows the agent to check the status of authorizations already requested and query active or inactive relationships."
• Business Details API: allows users/software developers to "list all businesses and retrieve additional information about the details of a user’s business."
• Business Income Source Summary API: allows users of third party applications to "retrieve a summary of income and expenditure for a specified self-employment, or property business for a given tax year."
• Business Source Adjustable Summary API: allows users of third party applications to "retrieve a Business Source Adjustable Summary (BSAS) calculation for a specified self-employment or property business, for a given accounting period," including:
• generating a list of BSAS
• generating a period end BSAS
• requesting a specific BSAS
• requesting the adjustments made to a specific self-employment BSAS
• provide accounting adjustments against a specified BSAS
• request the adjustments made to a specific property BSAS
• CIS Deductions API: allows users of third party applications to perform various functions regarding advance tax and National Insurance deductions made by contractors on subcontractors' payments and submitted to HMRC as part of the Construction Industry Scheme (CIS), including:
• retrieving details of the data submitted to HMRC by the contractor
• retrieving a list of CIS deductions
•  creating CIS deductions
•  removing CIS deductions
•  overriding previous CIS deductions following the end of tax year
• Individual Calculations API: allows users of third party applications to perform various functions including:
• triggering a self-assessment tax calculation
• listing all their annual self-assessment tax calculations
• retrieving their self-assessment tax calculation result using multiple endpoints
• listing self-assessment tax calculations for a given National Insurance number (NINO) and tax year
• triggering a self-assessment tax calculation for a given tax year, whose result can be explored via the "Retrieve a self-assessment tax calculation metadata" endpoint
• retrieving high-level calculation metadata for a given Calculation ID
• retrieving the calculated Income Tax and National Insurance contributions for a given NINO and Calculation ID
• retrieving the taxable income that has been used in the self-assessment tax calculation for a given NINO and Calculation ID
• retrieving the allowances, deductions and reliefs that exist for the self assessment tax calculation for a given NINO and Calculation ID
• retrieving the end-of-year Income Tax and National Insurance contribution estimates for a given NINO and Calculation ID
• retrieving "info", "warning," and "error" level messages linked to a Calculation ID
• Individual Losses API: allows users of third party applications to provide financial data regarding their Brought Forward Losses and Loss Claims including:
•  providing a list of brought forward losses and loss claims
•  creating a new brought forward loss and a loss claim against an income source for a specific tax year
•  showing a single brought forward loss and the detail of an existing loss claim
•  deleting an existing brought forward loss and a previously entered loss claim
•  updating an existing brought forward loss and a previously entered loss claim
• Individuals Business End of Period Statement API: allows users of third party applications to submit a declaration stating that the submission data for a business is complete.
• Individuals Charges API: allows users provide a customer’s financial data regarding their pension charges including creating, retrieving, amending, and deleting pension charges.
• Individuals Disclosures API: allows users of third party applications to create, retrieve, amend, and delete data relating to disclosures.
• Individuals Expenses API: allows users of third party applications to retrieve, delete, and amend expenses for both income for trade union and patent royalties and existing employment expenses as well as ignore HMRC provided employment expenses for a user.
• Individuals Income Received API: allows users of third party applications to create, amend, retrieve, or delete data regarding income from employment, insurance policies, foreign income, pensions, savings, and other income.
• Individuals Reliefs API: allows users of third party applications to create, amend, retrieve, and delete relief investments from seed and social enterprise investments, VCT subscriptions, community investments, and EIS subscriptions.
• Individuals State Benefits API: allows users of third party applications to create, delete, or amend customer added state benefits, list and retrieve state benefits, create or amend benefits financial data, as well as mark a state benefit as ignored.
• Obligations API: allows users of third party applications to retrieve the obligations for business income sources, the obligations for a user’s Income Tax account, and the End of Period Statement obligations for business income sources.
• Other Deductions API: allows users of third party applications to create, amend, delete, or retrieve deductions.
• Property Business API: allows users of third party applications to create, amend, delete, or retrieve an individual’s Foreign Property Annual Summary as well as create, amend, list, or retrieve their Foreign Property Income & Expenditure Period Summaries.
• Self Assessment API: allows users of third party applications to supply business and personal financial data to HMRC.
• Self Assessment Accounts API: allows users of third party applications to retrieve the following: "the overall liability broken down into overdue, payable and pending amounts; a list of charges and payments for a given date range; more detail about a specific transaction; a list of charges made to an account for a given date range; the history of changes to an individual charge; a list of payments for a given date range; and the allocation details of a specific payment against one or more liabilities."

(ii) Other API Functions

• Corporation tax: the interest restriction return API uses user-restricted endpoints in performing the following functions:
• Revoking an existing Reporting Company from submitting Interest Restriction Returns (IRR)
• Appointing a new Reporting Company for submitting IRRs
• Submitting a full IRR
• Submitting an abbreviated IRR
• National Insurance API: allows users of third party applications to "calculate a self-employed taxpayer's National Insurance liability within the self assessment tax calculation as well as retrieve an annual summary of an individual taxpayer's class 1 total earnings and class 2 National Insurance contributions due for a given tax year."
• PAYE-related APIs: The Marriage Allowance API allows users to "retrieve an individual’s Marriage Allowance status as well as check their partner’s eligibility to be a recipient of Marriage Allowance."
•  Self assessment-related APIs: These are user-restricted APIs and can only be accessed by third-party applications when authorized by the users. Examples include:
• The Individual Benefits API, Individual Income API, and Individua Tax API retrieves an individual's Self Assessment tax return information, including tax deductions and income from various sources.
• The National Insurance 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."
•  VAT (MTD) API: allows users to view and submit VAT returns as well as retrieve VAT obligations, liabilities, and payments.
• Check a UK VAT number API: allows users to "check if a UK VAT number is registered, view the name and address of the business that the UK VAT number is registered to get a reference number that you can use to prove you checked a UK VAT number."

3. Third Party Applications/Providers Approval Process

• There are two distinct registration processes for apps/software developers using HMRC's API: one for RESTful APIs and the other for XML APIs.

(i) RESTful APIs

• The registration process for creating a developer account to allow the integration of RESTful APIs is with a third party application is simple and straightforward, where providing the organization's name/details is optional.
• A link to the registration page can be found here. 
• Users need to fill in details about their first name, last name, email address, and password, with the option to include or exclude their organization.

(ii) XML

• On the other hand, XML software developers/apps require user to have a Vendor ID and the relevant test credentials to integrate their applications with XML APIs, which are obtained upon completion of the XML registration process.
• First, users need to contact the Software Developer Support Team by emailing the following details to SDSTeam@hmrc.gov.uk:
• The company name
• The company website address
• The contact name(s)
• The email address(es)
• The postal address, including postcode
• The telephone number(s)
• The XML API the app/user wants to develop
• HMRC will then conduct a basic background check on the organization, including the information held by Companies House as well as check the website.

4. License Agreement

• According to HMRC, although their terms of use do not create a legal relationship between themselves and any third party applications/software developers, they specify the expectation from both the department and the third party application integrating HMRC's APIs, which are hosted on their developer hub.

(i) Data Protection

• HMRC expects third party software/users of its APIs to protect users as well as their customer data by adhering to the following data protection laws:
•  National Cyber Security Centre’s Digital Service Security
•  National Cyber Security Centre’s Guidance for secure development and deployment  
•  Transport Layer Security principles for protecting data  
•  General Data Protection Regulation — UK GDPR  
•  Privacy and Electronic Communications (EC Directive) Regulations 2003 — as amended  
•  Equality Act 2010  
•  Information Commissioner’s Office  
•  Data Protection Act 2018 

(ii) Additional Acts and Regulations

•  Accessing Data: As the developer of a third party app integrating HMRC's API, "You must give your users access to their data and If you withdraw a piece of software or a user stops using it, you must let them retrieve and export all their data so they can meet their obligations to us."

•  Processing Data: You may need to pay a data protection fee if your software processes personal data as well as help protect user data by sending to HMRC particular types of user audit data.
•  Storing Data: For processed and stored data, you must inform users the personal data you intend to process, what you’ll use it for, your responsibility to protect the data, and your lawful basis for processing the user's personal data if you intend to store it outside the European Economic Area.
• A comprehensive coverage of the terms of use of HMRC's API can be found here, including the terms for data breaches, service standards, accessibility, advertising and marketing, license agreement between third party apps and their users, security issues, and software support to your users.

5. Usage Statistics

• Information surrounding the number of annual apps and/or users of HMRC's API platform appears limited in the public domain. The following are some helpful findings:
• The updated 2021 list of third party applications offering self assessment commercial software can be found here. 
• However, HMRC "does not recommend or endorse any one product or service over another and will not be responsible for any loss, damage, cost or expense in connection with using this software."
• A list of free payroll software for businesses with fewer than 10 employees, which have been tested by HMRC and are integrated with it to enable reporting can be found here. 
• A list of premium payroll software that have been tested and recognized by HMRC can be found here. 
• A list of both free and premium software for submitting VAT returns directly to HMRC without visiting the website, which have also been tested through HMRC’s recognition process can be found here. 
• HMRC was receiving around a million API calls per day as of October 2018, with 99.99% availability.
• Their 2018/2019 annual report stated that HMRC had reached 368 million requests to their API platform enabling interaction between commercial software used by businesses and agents and themselves, hence reducing the need for customers to contact them.

6. General Sentiment

• Although data surrounding the review/ratings of HMRC's API platform appears limited in the public domain, we have provided the general sentiment regarding their Making Tax Digital (MTD) initiative as a proxy.
• The Uk Government Gateway HMRC Individual Income API has a 5-star rating on Rapid API but it's based on one vote and it's only one out of a range of tax-related APIs provided by HMRC.
• HMRC launched its set of improved application programming interfaces (APIs) as part of MTD initiative to go paperless by 2023. The general sentiment regarding MTD is somewhat mixed with the positive sentiments citing an increase in opportunities, while the negative sentiments cite the increase in costs associated with the digitilization process.

(i) ICAEW Survey

• According to a 2019 survey carried out by ICAEW on 500 small and medium-sized firms via telephone, 73% of the respondents cited seeing digitalization as an opportunity, an increase from the 2018 survey results (46%), while 22% cited a significant increase in associated costs by more than 25%.  
• A full 88% of the respondents still have some clients using spreadsheets for record keeping, while 73% still keep records on paper.
• The following are some direct quotes from the respondents:
• "Quite frankly MTD has been a pain."
• "It's difficult because it's new to us and it's new to them and it's a struggle to find the time because you can't just magic it out of thin air."
• "The positive aspect is that we've had more touch points with clients than we had previously and there has been more need for our services on a more regular basis."

(ii) CIOT Survey

• According to a 2020 survey carried out by Chartered Institute of Taxation (CIOT), about 90% of respondents reported not finding any decrease in errors for MTD for VAT, WHILE 64% reported finding little impact from MTD on errors.
• A full 43% reported finding an average MTD for VAT implementation cost above £109 (the UK government’s estimate) but less than £500, while 11% reported costs above £5,000.
• A full 34% reported no impact on the productivity of their clients following the implementation of MTD for VAT, while 29% reported a small decrease in their clients’ productivity.

7. Authentication Process

• As outline above in the 'Third Party Applications/Providers Approval Process' section, the approval process for the integration and use of RESTful APIs with a third party application is simple and straightforward, while XML software developers/apps require user to have a Vendor ID and the relevant test credentials to integrate their applications with XML APIs.

(i) End points

• The platform's APIs have three types of endpoints determined by the level of authorization and access required.
• Open-access endpoints require no token for access by third party applications.
• On the other hand, application-restricted endpoints require an OAuth 2.0 access token generated using OAuth 2.0 Client Credentials Grant. 
• For user-restricted endpoints, third party applications require an OAuth 2.0 access token generated using OAuth 2.0 Authorization Code Grant. 

(ii) Credentials

• The credentials for third party applications include the client ID and the client secret, which are used to identify and authorize the application during each step of an OAuth 2.0 journey and when testing the application with sandbox APIs.
• The client ID is a unique identifier created by HMRC when adding the third party application to the developer hub.
• On the other hand, client secrets are unique passphrases, the equivalent of a password, which are generated to authorize third party application and are known only the application and the authorizing server.

(iii) 2-step Verification

• The 2-step verification (2SV) is a process of providing extra security for user-restricted endpoints when getting an OAuth 2.0 access token, which follows the user signing in step.
• Users are required to have their mobile or landline phone on hand to receive the token generated except for the first time they register for the service, where they must register for 2SV.
• Users are given the option to receive a 6-digit code via SMS on their mobile phone or voice message through their landline or a QR code displayed on-screen on the app to be scanned using a device running an authentication app.
• Additionally, for the second and subsequent sign ins, the user "must complete 2SV using their chosen method. Because 2SV is part of the API authorization process, users do not need to complete it every time they use an API, only when their token expires (after 18 months) or if they are granting access to additional scopes."
• The illustration below shows the 2-step verification journey for users.

 

Source

(8) Key Users

• Precompiled information outlining the key users, including their demographic characteristics appears limited in the public domain. The following are some helpful findings:

• Based on the analysis of the software vendors listed in HMRC's website, who the department recommends to various legal entities, including businesses and individuals, the key users of its APIs are developers of commercial record keeping and bridging apps with both mobile and enterprise-level support for businesses and agents as well as payroll, human resource, and accounting software vendors for businesses of all scales, i.e small, medium, and large enterprises.
• An analysis of the payroll software vendors recommended by HMRC, for instance, reveals Cloud Payroll with mobile support and 12Pay Payroll which offers products for businesses of all sizes, i.e express, premium, and bureau product types.
• The company's express products are ideal for companies with up to 9 employees where digital payslips and management reports are not required.
• The premium product is perfect for running payroll for a small number of companies with up to 30 employees.
• On the other hand, the Bureau software product is ideal for accountants and bureaus running payroll for many companies with a ranging number of employees numbers.
• The software vendors recognized by HMRC can be found here (VAT), here (payroll software), and here (self assessment).

Research Strategy