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.

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

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	An OAuth 2.0 Bearer Token. For example: `Bearer 59fc92c1cdf0b8ef1f138a702effdbd2`

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"
      ]
    }
  ]
}

Response table
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

Path parameters table
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

Query parameters table
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

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`
Authorization required	An OAuth 2.0 Bearer Token. For example: `Bearer 59fc92c1cdf0b8ef1f138a702effdbd2`

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": []
        }
      ]
    }
  ]
}

Response table
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

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