• Register
• Sign in

 

This version is in beta - expect some breaking changes.

Test Fraud Prevention Headers API

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. Check the data you need to send.

Do not send HMRC your Test API logs. We use your most recent submissions to the sandbox to check your fraud prevention headers.

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.

Skip to main content

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 and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

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	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 submitted. These are required by law. Check the specification."
}

All fraud prevention headers appear to be valid

{
  "specVersion": "2.x",
  "code": "VALID_HEADERS",
  "message": "All headers required for your connection method have been supplied and all appear to be valid. Validation is based on a single request. 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": "At least 1 header is potentially invalid",
  "warnings": [
    {
      "code": "POTENTIALLY_INVALID_HEADER",
      "message": "Check you are using the correct Gov-Client-Connection-Method. Web applications do not usually provide the os field as browsers do not expose this information.",
      "headers": [
        "gov-client-user-ids"
      ]
    }
  ]
}

Some fraud prevention headers may be invalid

{
  "specVersion": "2.x",
  "code": "INVALID_HEADERS",
  "message": "At least 1 header is invalid",
  "errors": [
    {
      "code": "INVALID_HEADER",
      "message": "Invalid offset value. Submit  UTC±<hh>:<mm>",
      "headers": [
        "gov-client-timezone"
      ]
    },
    {
      "code": "MISSING_HEADER",
      "message": "Header required",
      "headers": [
        "gov-vendor-version"
      ]
    },
    {
      "code": "INVALID_HEADERS",
      "message": "At least 1 pair of IPs in Gov-Vendor-Forwarded must include Gov-Client-Public-IP in the 'for' field and Gov-Vendor-Public-IP in the 'by' field. Check all 3 headers are consistent.",
      "headers": [
        "gov-vendor-forwarded",
        "gov-vendor-public-ip",
        "gov-client-public-ip"
      ]
    }
  ],
  "warnings": [
    {
      "code": "POTENTIALLY_INVALID_HEADER",
      "message": "Check you are using the correct Gov-Client-Connection-Method. Web applications do not usually provide the os field as browsers do not expose this information.",
      "headers": [
        "gov-client-user-ids"
      ]
    }
  ]
}

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

Skip to main content

Is this page not working properly? Is this page not working properly?