Getting it right
How we check data
We monitor API calls from all applications. We run automated tests to check data meets the requirements and is formatted correctly. In addition, we manually test data to make sure values are realistic and what we expect.
What statuses mean
Missing, Invalid, Errors or Advisories header statuses mean you have issues to fix or review.
Correct header status means we have not found any issues this month, and your application currently meets the fraud prevention specification - not that your application is ‘compliant’.
Check your application
You can now check your application’s fraud prevention headers on Developer Hub at any time.
To check your fraud prevention headers
- Log in to Developer Hub
- Go to View all applications
- Select your Production application
- On the left, select ‘Fraud prevention’
We no longer send detailed reports to you every month.
Now we send a monthly email telling you the status of your application, and what you need to do. The right people in your organisation need to receive the email - make sure they are all registered on HMRC’s Developer Hub.
Before you submit any header data, use the Test API.
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
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
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.