Skip to main content

Getting it right

Version 3.0 issued 6 January 2021
Check what has changed

Send data in the correct format

Header data contents must be submitted using the US-ASCII character set, with other characters percent encoded (opens in a new tab).

Each header has additional formatting requirements. To check a header format, you need to select your connection method.

Key-value encoding

Whenever a header contains a key-value data structure, you must use this format:

<key-1>=<value-1>&<key-2>=<value-2>&…

Whenever a key is applicable but has no applicable value, you can omit the key-value pair or include the key with an empty value.

Keys and values must be percent encoded (opens in a new tab).

Key-value pairs can be submitted in any order.

List encoding

Whenever a header contains a list, you must use this format:

<value-1>,<value-2>,…

Values must be percent encoded (opens in a new tab).

Values must not be empty.

How we check data

We monitor API calls from all applications. If data submitted by your application has errors or warnings, we’ll email a report with the details. We email reports once a month.

It is important that the right people in your organisation receive the reports. You’ll need to check who that is and make sure they are registered on HMRC’s Developer Hub.

To help avoid errors and warnings, use the Test API.

Missing header data

Warning You are required by law to submit all header data for your connection method.

Most organisations are able to send all header data required for their connection method.

In exceptional cases you may be unable to collect a value due to restrictions beyond your reasonable control, such as:

  • operating system or platform restrictions
  • security measures
If you are unable to submit a header, you must contact us to explain why. Make sure you include full details of the restrictions.

After discussing a missing header with us, you can omit the header or submit it with an empty value. You must not include a placeholder value, for example null or undefined.

Using third-party software and libraries

If you use or plan to use third-party software and libraries, make sure you can still collect header data. Examples include an extension to an Enterprise Resource Planning (ERP) system or a plug-in to a spreadsheet application.

Contact us

You can send an email to SDSTeam@hmrc.gov.uk.

If you are explaining an exceptional case that means you cannot collect a value, include as many details as you can.

Change log

Version 3.0

12 July 2021

  • Clarification on fields for Gov-Client-User IDs

This will be updated in the Directions.

3 June 2021

  • Added a link to the Compliance and Sanctions Guidelines

30 April 2021

  • Clarification on the format for Gov-Client-Public-IP-Timestamp and Gov-Client-Local-IPs-Timestamp

This will be updated in the Directions.

6 January 2021

  • Gov-Client-Local-IPs-Timestamp is a new header for all connection methods
  • Gov-Client-Public-IP-Timestamp is a new header for via server connection methods
  • Gov-Vendor-Product-Name is a new header for all connection methods
  • Gov-Client-Device-ID must be submitted as a universally unique identifier (UUID)
  • Gov-Client-User-Agent must be submitted as a key-value structure
  • Clarification that Gov-Client-Multi-Factor accepts seconds and milliseconds
  • Clarification on when to collect values for Gov-Client-Local-IPs

To check what you need to send, select your connection method.