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.
Whenever a header contains a key-value data structure, you must use this format:
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.
Whenever a header contains a list, you must use this format:
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
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
For example, an application connecting directly to HMRC might not be able to submit a username for Gov-Client-User-IDs if the originating device does not have user accounts.
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
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.
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.
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.