Getting it right
Version 2.9 issued 14 July 2020
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.
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.
If you leave a header empty, do not submit any value including null values. These examples are not valid:
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.