Skip to main content
Table of contents

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.

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.

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

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 are unable to submit a header, you must contact us to explain why. Make sure you include full details of the restrictions.

If you leave a header empty, do not submit any value including null values. These examples are not valid:

  • Gov-Client-User-IDs: null
  • Gov-Client-User-IDs: nil
  • Gov-Client-User-IDs: 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.