Terms of use

Version 1.2 issued 18 December 2018

These terms of use explain what you can expect from us and what we expect from you when creating and operating software services that consume HMRC Application Programming Interfaces (APIs) hosted on the HMRC Developer Hub. They do not create a legal relationship between HMRC and any software developer.

We reserve the right to remove your access to the Developer Hub and its APIs temporarily or permanently.

These terms may change from time to time and we will let you know when this happens. For major changes you may need to re-accept these terms of use, but for minor changes we will assume you agree to the changes unless we hear from you.

If you have any questions ask for support.

Background checks

We’ll carry out basic background checks on your organisation. They include checking:

  • information held by Companies House
  • your website

What you can expect from us

We will:

  • give you at least 6 months’ notice of changes affecting any stable APIs
  • make sure any minor changes made to stable APIs are backwards compatible
  • provide reasonable notice of changes affecting beta APIs, which can change fairly frequently
  • warn you before we retire an API
  • provide a robust test environment

What we expect from you

We take the protection of customer data seriously. We expect you to do the same by following data protection law and protecting users in line with the:

You must also follow these acts and regulations if they’re changed or replaced.

Accessing data

You must give your users access to their data. We may also ask to access their data if we open an investigation.

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.

We recommend using multi-factor authentication to protect personal data.

Processing data

You may need to pay a data protection fee (opens in a new tab) if your software processes personal data.

You must help us protect our users’ confidential data by sending us particular types of user audit data which we will record. Our APIs provide HTTP headers that you can use to pass this audit data to us. See how to do this under fraud prevention.

Supplying header information for all our APIs will become mandatory - so we recommend designing it into your applications now.

To find out if header information is mandatory for an API that you use, read its API documentation.

Storing data

If you store and process their personal data, you must tell users:

  • what personal data you’ll be processing and what you’ll use it for
  • that you’re responsible for protecting their data
  • if you intend to store their data outside the European Economic Area
  • your lawful basis (opens in a new tab) for processing their personal data

If you need users’ consent to store and process their personal data you’ll need to follow UK GDPR rules on obtaining consent (opens in a new tab).

If you store or process data outside the European Economic Area, you must follow UK GDPR guidance on international transfers (opens in a new tab).

You must store data to meet our policy on keeping your pay and tax records (opens in a new tab).

Data breaches

If there’s a data breach or any other issue concerning customer data you must tell us immediately by emailing SDSTeam@hmrc.gov.uk.

Under UK GDPR rules, you must also notify ICO about certain types of personal data breach (opens in a new tab) within 72 hours of becoming aware of it.

Service standard

Your software must take into account the Digital Service Standard.


You must:

Advertising and marketing

Any advertising that appears in your software must follow both:

You must not use advertising that promotes:

  • adult themes
  • dating
  • gaming

You cannot share personal data for marketing without users’ consent, as defined in the Direct Marketing Guidance PDF from the Information Commissioner’s Office (opens in a new tab).

You cannot advertise your software as ‘HMRC accredited’, ‘HMRC endorsed’, ‘HMRC certified’ or similar.

You cannot use our HMRC brand in any way including logo placement on your website.

Licence agreements

You must make the terms of the licence agreement between you and your users clear to them.


You must:

  • check software for vulnerabilities through secure development and pre-release testing
  • check open source or reused proprietary code using resources like the Common Vulnerabilities and Exposures (opens in a new tab) database
  • react quickly if you find vulnerabilities in your code
  • have a patching policy in place

Your re-releases and upgrades should also follow secure development practices and pre-release testing.

We recommend following the security principles of:

Suspicious activity

We expect you to look out for and block suspicious attempts to access or manipulate user accounts.


You must give software support to your users. If you need help ask for support.

Dispute process

  1. We’ll contact you if we learn about an issue that affects us or your clients.
  2. We’ll work together to solve the issue.
  3. If the problem’s under your control we expect you to solve it straight away.
  4. If you can’t solve it, we’ll refer it to your managing director or accountable officer.
  5. If we can’t find a solution together, we’ll remove your access to the API Platform temporarily or permanently.
  6. If we remove your access, we’ll tell your users and give them time to find other ways to submit information - during this period we won’t give them penalties or charge interest for late submissions.
  7. We can remove your access to the API Platform for a number of reasons, including:
    • using personal data for something the user has not given you permission for
    • having serious data or cybersecurity concerns for our systems or customer data
    • not maintaining and supporting your product
    We can also remove your access if you don’t follow the rules around paying taxes or making social security contributions, as long as:
    • it’s supported by a final UK court decision (or the equivalent in the country you’re based)
    • or we can show you’ve broken those rules in another way
    However, we won’t remove your access in this case if you’ve repaid everything you owe (plus interest and fines), or you’ve made arrangements with us to pay the amount.
  8. If you’re listed on GOV.UK, we may remove you.
To agree to the terms of use for each of your applications, you must sign in to your account.