Test Fraud Prevention Headers API
Date | Amount |
---|---|
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.
warnings
.
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.
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+json
|
Gov-*
required
|
Add the fraud prevention headers to be validated as separate HTTP headers. 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.
Responses
HTTP status 200 (OK)
No fraud prevention headers provided
{ "specVersion": "3.1", "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.1", "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 advisories are given
{ "specVersion": "3.1", "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.1", "code": "INVALID_HEADERS", "message": "At least 1 header is invalid", "errors": [ { "code": "INVALID_HEADER", "message": "Value must be a recognised timezone in UTC format, submitted as 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 advisory. |
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.
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
self-employment-business-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. application/vnd.hmrc.1.0+json
|
Authorization
required
|
An OAuth 2.0 Bearer Token.
For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2
|
See also fraud prevention.
Responses
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×tamp=2017-04-21T13%3A23Z&unique-reference=c672b8d1ef56ed28,type=TOTP×tamp=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