Test Fraud Prevention Headers - HMRC Developer Hub

Version and status
Available in Sandbox	Yes
Sandbox base URL	https://test-api.service.hmrc.gov.uk
Available in Production	No

Overview

The Test Fraud Prevention Headers API allows you to check that the fraud prevention headers submitted by your application are formatted correctly and meet the requirements of HMRC’s fraud prevention specification.

What are fraud prevention headers?

Fraud prevention headers are HTTP headers that help us monitor and audit transactions to protect taxpayers’ data from fraudulent activities.

It is mandatory to supply fraud prevention header information for all applications calling the VAT (MTD) API endpoints.

What can I do with this API?

Use this API to ensure your application is able to produce correctly formatted fraud prevention headers. It can be used during the initial development phase and as part of your regular quality assurance checks.

What does this API do?

This API performs basic checks on the values and formats of the fraud prevention header values sent by your application

For example:

is the value for Gov-Client-Public-IP an IP address?
is the IP address value for Gov-Client-Public-IP a public IP?

Feedback provided is based on data that you provide in a single request but does not guarantee that all your requests in production will meet the requirements of the fraud prevention specification. Responses from the VAT (MTD) API are currently not affected by the presence of fraud prevention headers.

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

200 if request has been processed and feedback has been provided
400 to 499 if it failed because of a client error by your application
500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Endpoints

/test/fraud-prevention-headers/validate

Test Fraud Prevention Headers

GET

This resource validates fraud prevention headers submitted with this HTTP request.

Authorisation

This endpoint is application-restricted - it requires an Authorization header containing a server_token or an OAuth 2.0 Bearer Token.

Request headers

Request headers Table
Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: `application/vnd.hmrc.1.0+json`
Gov-* required	Add the fraud prevention headers to be validated as separate HTTP headers. For example: `Gov-Client-Connection-Method: DESKTOP_APP_DIRECT Gov-Client-Device-ID: 3d8a8d57-1af9-4ccb-b87c-5bb7d05d9be7 Gov-Client-Timezone: UTC+00:00 ...`
Authorization required	A bearer token which is either your application's `server_token` or an OAuth 2.0 Bearer Token. For example: `Bearer 59fc92c1cdf0b8ef1f138a702effdbd2`

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

No fraud prevention headers provided

{
  "specVersion": "2.x",
  "code": "INVALID_HEADERS",
  "message": "No fraud prevention headers have been provided. We need Gov-Client-Connection-Method header value to perform validation and to identify the list of other headers that will be required for your connection method."
}

All fraud prevention headers appear to be valid

{
  "specVersion": "2.x",
  "code": "VALID_HEADERS",
  "message": "All of the headers required for your connection method have been supplied and all of those headers appear to be valid. Validation is based on a single request. In production we have access to all requests and can draw additional conclusions."
}

Some fraud prevention headers where warnings are given

{
  "specVersion": "2.x",
  "code": "POTENTIALLY_INVALID_HEADERS",
  "message": "Some of the supplied headers are potentially invalid.",
  "warnings": [
    {
      "code": "POTENTIALLY_INVALID_HEADER",
      "message": "Web applications do not usually provide the 'os' field. The 'os' field should be that of the originating device and should be empty for web applications, and populated for other types of applications where operating system username is discoverable. Please ensure that the Gov-Client-Connection-Method header correctly reflects the architecture of your application.",
      "headers": [
        "gov-client-user-ids"
      ]
    }
  ]
}

Some fraud prevention headers may be invalid

{
  "specVersion": "2.x",
  "code": "INVALID_HEADERS",
  "message": "Some of the supplied headers are invalid.",
  "errors": [
    {
      "code": "INVALID_HEADER",
      "message": "Header value is not in the format: 'UTC±<hh>:<mm>'. The offset value (hh:mm) provided is not correct.",
      "headers": [
        "gov-client-timezone"
      ]
    },
    {
      "code": "MISSING_HEADER",
      "message": "Header is missing.",
      "headers": [
        "gov-vendor-version"
      ]
    },
    {
      "code": "INVALID_HEADERS",
      "message": "One pair of IPs in the Gov-Vendor-Forwarded header should include IPs from Gov-Client-Public-IP (in the 'for' field) and Gov-Vendor-Public-IP (in the 'by' field). Please review all 3 headers and ensure consistency.",
      "headers": [
        "gov-vendor-forwarded",
        "gov-vendor-public-ip",
        "gov-client-public-ip"
      ]
    }
  ],
  "warnings": [
    {
      "code": "POTENTIALLY_INVALID_HEADER",
      "message": "Use a UUID (also known as a GUID) as recommended in our documentation.",
      "headers": [
        "gov-client-device-id"
      ]
    },
    {
      "code": "POTENTIALLY_INVALID_HEADER",
      "message": "ID needs to be longer to help ensure it is unique. As a benchmark we use a UUID which is 128 bits or 32 hex characters long.",
      "headers": [
        "gov-client-device-id"
      ]
    },
    {
      "code": "POTENTIALLY_INVALID_HEADER",
      "message": "Header value contains an email address. Device ID should not be derived from user-specific data.",
      "headers": [
        "gov-client-device-id"
      ]
    },
    {
      "code": "UNEXPECTED_HEADER",
      "message": "Header is not one of fraud prevention headers.",
      "headers": [
        "gov-test-scenario"
      ]
    }
  ]
}

Response table
Name	Description
specVersion string required	The version of fraud prevention headers that request was validated against. This value will change whenever a major version of the spec is released (i.e. from 2.x to 3.x).
message string required	The validation message
code string required	The validation code
errors array optional	Array of errors
code string required	The error code
message string required	The error message
headers array required	Array of headers the error applies to
warnings array optional	Array of warnings
code string required	The warning code
message string required	The warning message
headers array required	Array of headers the warning applies to

Test data

Test Data section is not applicable for this API.

Validation codes

Code	Description
VALID_HEADERS	Basic checks show that the header value supplied appears to be valid
INVALID_HEADERS	Basic checks show that at least one of the header values supplied is not valid
INVALID_HEADER	Basic checks show that the header value supplied is not valid
POTENTIALLY_INVALID_HEADERS	Basic checks show that at least one of the header values supplied is potentially invalid as per current specification. However, this might turn into an INVALID_HEADER when further checks are performed or fraud prevention header specification is updated
POTENTIALLY_INVALID_HEADER	Basic checks show that the header value supplied is potentially invalid as per current specification. However, this might turn into INVALID_HEADER when further checks are performed or fraud prevention header specification is updated
MISSING_HEADER	Header required for the connection method is not supplied
EMPTY_HEADER	Header required for the connection method is empty
UNEXPECTED_HEADER	Header value supplied is not a fraud prevention header, or the fraud prevention header is misspelt

Close section