Device Fingerprinting API

Three endpoints that record and check the device a visit came from. They feed the fraud detection that can refuse a click.

You normally do not call these. The embedded offerwall collects a fingerprint and posts it automatically every time the wall loads. They are documented here so you can understand why a legitimate click might be refused, and so you can call them directly from a custom integration.

Authentication

These endpoints require no credentials. Unlike GET /api/v1/offers, which needs apiKey and apiSecret, the fingerprint endpoints accept anonymous POST requests.

Treat that as a reason not to send anything sensitive through them. There is no way to attribute a call to a particular app.

All three sit under the general API rate limit of 60 requests per minute.

Record a fingerprint

POST https://preads.hansaldev.com/api/v1/fingerprint

Field	Required	Type	Description
`fingerprint_hash`	Yes	string, max 255	Your stable identifier for this device.
`fingerprint_data`	Optional	object	The raw signals you collected, if any.
`confidence_score`	Optional	number, 0–1	How reliable you consider the fingerprint.
`user_id`	Optional	string	Your end user identifier, so the record can be tied to them.

Example request:

curl -X POST "https://preads.hansaldev.com/api/v1/fingerprint" \
  -H "Content-Type: application/json" \
  -d '{
        "fingerprint_hash": "9f2c1a7be4d83f60",
        "confidence_score": 0.92,
        "user_id": "user_8812"
      }'

Response:

{
  "success": true,
  "fingerprint_hash": "9f2c1a7be4d83f60",
  "device_id": 412,
  "is_blocked": false,
  "is_new_device": true,
  "times_seen": 1,
  "risk_score": 15,
  "warnings": []
}

Response field	Meaning
`device_id`	Internal record ID for this device.
`is_blocked`	The device is on a block list. Clicks from it will be refused.
`is_new_device`	First time this device has been seen.
`times_seen`	How many times this fingerprint has been recorded.
`risk_score`	0–100. Higher means more suspicious.
`warnings`	Any of Device is blocked, Multiple accounts detected, Bot signatures detected, High risk device. Empty when nothing stands out.

Errors: 422 with { "success": false, "error": "Invalid fingerprint data", "details": { ... } } when the payload fails validation; 500 with { "success": false, "error": "Failed to store fingerprint" } if storage fails.

Check a fingerprint

POST https://preads.hansaldev.com/api/v1/fingerprint/verify

Takes a single fingerprint_hash and reports whether it is currently acceptable.

{
  "success": true,
  "is_valid": false,
  "message": "Fingerprint blocked or invalid"
}

is_valid: false means the fingerprint is unknown or blocked. It does not distinguish the two cases.

Check for multi-accounting

POST https://preads.hansaldev.com/api/v1/fingerprint/check-multi-account

Reports whether the same device has been associated with more than one user.

{
  "success": true,
  "is_multi_accounting": true
}

Note that this is an observation, not an accusation. Shared devices — a family tablet, an office machine, a carrier NAT — legitimately produce true.

How this connects to click tracking

The wall sends the fingerprint with every click it registers, to GET /api/track as the fingerprint parameter. Before recording the click, Preads scores it. If the score trips a rule, the click is refused:

403 Access Denied: Suspicious Activity Detected (<reason>)

The refusal is returned to the click, not shown on the wall, so it appears to a visitor as a failed new tab.

Common causes of a legitimate click being refused: many clicks from one userId or one IP in a short window, several user accounts behind a single device, or a device already on a block list. If you need to raise a block, contact your platform operator.

Notes

user_id on the record endpoint is accepted but not validated. It is your own identifier; do not rely on Preads to sanitise it.
Fingerprints are stored, not deleted on request through this API. There is no removal endpoint.
Sending a fingerprint does not guarantee a click will be accepted — it is one input among several.