Fraud and Risk Prevention

/

API reference

/

Device Fingerprinting

/

Fingerprint Lookup

Fingerprint Lookup

POSThttps://telemetry.stytch.com/v1/fingerprint/lookup

Lookup the associated fingerprint to the telemetry ID returned from the GetTelemetryID. Learn more about the different fingerprint types and verdicts in our DFP guide.

Make a decision based on the returned verdict:

  • ALLOW - This is a known valid device grouping or device profile that is part of the default ALLOW listed set of known devices by Stytch. This grouping is made up of verified device profiles that match the characteristics of known/authentic traffic origins.
  • BLOCK - This is a known bad or malicious device profile that is undesirable and should be blocked from completing the privileged action in question.
  • CHALLENGE - This is an unknown or potentially malicious device that should be put through increased friction such as 2FA or other forms of extended user verification before allowing the privileged action to proceed.

If the telemetry_id is not found, we will return a 404 telemetry_id_not_found error. We recommend treating 404 errors as a BLOCK, since it could be a sign of an attacker trying to bypass DFP protections by generating fake telemetry IDs.


Body parameters


telemetry_id*string

external_metadataobject

Response fields


request_idstring

status_codeint

fingerprintsobject

verdictobject

external_metadataobject

propertiesobject
curl --request POST \
  --url 'https://telemetry.stytch.com/v1/fingerprint/lookup' \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "telemetry_id": "026ac93b-8cdf-4fcb-bfa6-36a31cfecac1"
  }'

RESPONSE

200
{
	"created_at": "2023-01-01T00:00:00Z",
	"expires_at": "2033-01-01T00:00:00Z",
	"external_metadata": {
	    "external_id": "user-123",
	    "organization_id": "organization-123",
	    "user_action": "LOGIN"
	},
	"properties": {
        "browser_properties": {
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"
        },
        "network_properties": {
            "asn": {
                "asn": "64511",
                "name": "Stytch Network",
                "network": "192.0.2.0/24"
            },
            "ip_address": "192.0.2.0",
            "ip_geolocation": {
                "city": "San Francisco",
                "country": "US",
                "region": "California"
            },
            "is_proxy": false,
            "is_vpn": false
        }
    },
	"fingerprints": {
		"browser_fingerprint": "browser-fingerprint-0b535ab5-ecff-4bc9-b845-48bf90098945",
		"browser_id": "browser-id-99cffb93-6378-48a5-aa90-d680232a7979",
		"hardware_fingerprint": "hardware-fingerprint-4af7a05d-cf77-4ff7-834f-0622452bb092",
		"network_fingerprint": "network-fingerprint-b5060259-40e6-3f29-8215-45ae2da3caa1",
		"visitor_fingerprint": "visitor-fingerprint-6ecf5792-1157-41ad-9ad6-052d31160cee",
		"visitor_id": "visitor-6139cbcc-4dda-4b1f-b1c0-13c08ec64d72"
	},
	"status_code": 200,
	"telemetry_id": "026ac93b-8cdf-4fcb-bfa6-36a31cfecac1",
	"verdict": {
		"action": "ALLOW",
		"detected_device_type": "...",
		"is_authentic_device": true,
		"reasons": [...]
	}
}