This version is in beta - expect some breaking changes.

Test Fraud Prevention Headers API

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

Overview

When you use some of our APIs, you need to submit fraud prevention headers. This API checks the fraud prevention headers on individual requests. It checks the value and format and gives you feedback on any issues. For example, is the value for Gov-Client-Public-IP a public IP address?

How to use this API

Use this API to check headers submitted by your application meet the latest version of the fraud prevention headers specification.

In the initial stages of development, use the validate endpoint to get immediate feedback for a single request.

Once you have implemented headers on your API requests, run tests in sandbox. Then, use the validation-feedback endpoint to get feedback on the last request made to each endpoint.

We refer to your software architecture as a connection method. To use this API, you need to select the correct connection method for your application.

What not to do

Make sure that you:

  • do not use this API as a guarantee that requests in production will meet the specification
  • do not send HMRC your logs from this API. We use your most recent submissions to the sandbox to check 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

Validate 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.

Response

HTTP status: 200 (OK)

No fraud prevention headers provided 

{
  "specVersion": "3.0",
  "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": "3.0",
  "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": "3.0",
  "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": "3.0",
  "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 specification that the request was validated against. This value will change when a major version of the specification is released.
message
string
required

A summary of the overall outcome of the fraud prevention header checks.
code
string
required

A machine-readable code showing the overall validation result.

Limited to the following possible values:

VALID_HEADERS - basic checks show that the header value supplied appears to be valid.
INVALID_HEADERS - basic checks show that at least 1 of the header values supplied is not valid.
POTENTIALLY_INVALID_HEADERS - basic checks show that at least 1 of the header values supplied is potentially invalid as per the current specification.
errors
array
optional
code
string
required

A machine-readable code indicating the type of error.

Limited to the following possible values:

INVALID_HEADER - basic checks show that the header value supplied is not valid.
INVALID_HEADERS - basic checks show that at least 1 of the header values supplied is not valid.
MISSING_HEADER - header required for the connection method is not supplied.
EMPTY_HEADER - header required for the connection method is empty.
message
string
required

A description of the error.
headers
array
required

A list of headers that have the error.
warnings
array
optional
code
string
required

A machine-readable code indicating the type of error.

Limited to the following possible values:

POTENTIALLY_INVALID_HEADER - basic checks show that the header value supplied is potentially invalid as per the current specification.
UNEXPECTED_HEADER - header value supplied is not a fraud prevention header, or the fraud prevention header is not spelt correctly.
message
string
required

A description of the error.
headers
array
required

A list of headers that have the warning.

Close Section
/test/fraud-prevention-headers/{api}/validation-feedback

Get feedback on requests made to an API
GET

Use this resource to get feedback on fraud prevention headers submitted by your application in sandbox. You'll get detailed feedback on the most recent request to each endpoint of a supported API.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Path parameters

Name Description
api
string
required

Identifies the API to get feedback on.

Limited to the following possible values:

business-details-mtd
business-income-source-summary-mtd
business-source-adjustable-summary-mtd
cis-deductions-mtd
individual-calculations-mtd
individual-losses-mtd
individuals-business-end-of-period-statement-mtd
individuals-charges-mtd
individuals-disclosures-mtd
individuals-expenses-mtd
individuals-income-received-mtd
individuals-reliefs-mtd
individuals-state-benefits-mtd
obligations-mtd
other-deductions-mtd
property-business-mtd
self-assessment-mtd
self-assessment-accounts-mtd
vat-mtd

Query parameters

Name Description
connectionMethod
string
optional

If your application uses more than 1 connection method, you can use this query parameter to filter by connection method.

Limited to the following possible values:

BATCH_PROCESS_DIRECT
DESKTOP_APP_DIRECT
DESKTOP_APP_VIA_SERVER
MOBILE_APP_DIRECT
MOBILE_APP_VIA_SERVER
OTHER_DIRECT
OTHER_VIA_SERVER
WEB_APP_VIA_SERVER

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
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Response

HTTP status: 200 (OK)

{
  "requests": [
    {
      "path": "/organisations/vat/107794340/liabilities",
      "method": "GET",
      "requestTimestamp": "2020-09-21T10:30:05.962Z",
      "code": "INVALID_HEADERS",
      "headers": [
        {
          "header": "gov-client-connection-method",
          "value": "DESKTOP_APP_VIA_SERVER",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-device-id",
          "value": "beec798b-b366-47fa-b1f8-92cede14a1ce",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-local-ips",
          "value": "10.1.2.3,10.3.4.2",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-local-ips-timestamp",
          "value": "2020-09-21T10:30:05.123Z",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-mac-addresses",
          "code": "MISSING_HEADER",
          "errors": [
            "Header required"
          ],
          "warnings": []
        },
        {
          "header": "gov-client-multi-factor",
          "value": "type=AUTH_CODE&timestamp=2017-04-21T13%3A23Z&unique-reference=c672b8d1ef56ed28,type=TOTP&timestamp=2017-05-19T13%3A10Z&unique-reference=ac73430ffdfd9",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-public-ip",
          "value": "198.51.100.0",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-public-ip-timestamp",
          "value": "2020-09-21T10:30:05.123Z",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-public-port",
          "value": "12345",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-screens",
          "value": "width=1920&height=1080",
          "code": "INVALID_HEADER",
          "errors": [
            "At least 1 screen is missing a value for scaling factor",
            "At least 1 screen is missing a value for colour depth"
          ],
          "warnings": []
        },
        {
          "header": "gov-client-timezone",
          "value": "UTC+00:00",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-user-agent",
          "value": "os-family=Windows&os-version=Server%202012&device-manufacturer=Dell%20Inc.&device-model=OptiPlex%20980",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-user-ids",
          "value": "os=user123",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-client-window-size",
          "value": "width=1256&height=803",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-vendor-forwarded",
          "value": "by=203.0.113.6&for=198.51.100.0",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-vendor-license-ids",
          "value": "my%20licensed%20software=8D7963490527D33716835EE7C195516D5E562E03B224E9B359836466EE40CDE1",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-vendor-public-ip",
          "value": "203.0.113.6",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-vendor-product-name",
          "value": "Product%20Name",
          "code": "VALID_HEADER",
          "errors": [],
          "warnings": []
        },
        {
          "header": "gov-vendor-version",
          "value": "my-desktop-app=2.2.2",
          "code": "POTENTIALLY_INVALID_HEADER",
          "errors": [],
          "warnings": [
            "For client server architectures, submit a version for the client and the server. For all other architectures, submit at least 1 version."
          ]
        }
      ],
      "crossValidation": [
        {
          "headers": [
            "gov-vendor-forwarded",
            "gov-vendor-public-ip",
            "gov-client-public-ip"
          ],
          "code": "VALID_HEADERS",
          "errors": []
        }
      ]
    }
  ]
}

Name Description
requests
array
required

A list containing feedback on the latest request submitted to each API endpoint.
path
string
required

The path the request was submitted to.
method
string
required

The HTTP method used for the request.
requestTimestamp
string
required

The timestamp of when the request was submitted.
code
string
required

A machine-readable code indicating the validation result for the request.

Limited to the following possible values:

VALID_HEADERS - basic checks show that the header values supplied appear to be valid.
INVALID_HEADERS - at least 1 of the header values supplied is not valid, check errors and warnings.
POTENTIALLY_INVALID_HEADERS - at least 1 of the header values supplied is potentially invalid, check warnings.
NO_HEADERS - the request did not have any fraud prevention headers.
headers
array
required

A list containing each of the Gov-* headers submitted with the request.
header
string
required

The name of the header.
value
string
optional

The value submitted for this header.
code
string
required

A machine-readable code indicating the validation result for the header.

Limited to the following possible values:

VALID_HEADER - basic checks show that the header value supplied is valid.
INVALID_HEADER - the header value supplied is not valid, check errors and warnings.
POTENTIALLY_INVALID_HEADER - the header value supplied is potentially invalid, check warnings.
MISSING_HEADER - header required for the connection method is not supplied.
UNEXPECTED_HEADER - header is not needed for the connection method, is not a fraud prevention header, or is not spelt correctly.
TEST_SCENARIO_HEADER - header is used in sandbox testing to trigger different test scenarios.
errors
array
required

A list of error messages in the validation result for the header value.
warnings
array
required

A list of warning messages in the validation result for the header value.
crossValidation
array
required

A list of validations involving multiple headers.
headers
array
required

A list of the headers included in the validation.
code
string
required

A machine-readable code indicating the result of cross validation.

Limited to the following possible values:

VALID_HEADERS - cross checks identified no problems with the headers.
INVALID_HEADERS - cross checks identified one or more problems with the headers, check errors.
errors
array
required

A list of error messages resulting from cross validation of header values.

Close Section

Skip to main content

Is this page not working properly? (opens in new tab)