Fingerprint Lookup

POST

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

Lookup the associated fingerprint for the telemetry_id returned from the GetTelemetryID() function. 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_metadata object

Response fields

request_id string

status_code int

telemetry_id string

fingerprints object

verdict object

external_metadata object

created_at string

expires_at string

properties object

const stytch = require('stytch');

const client = new stytch.Client({
  project_id: 'PROJECT_ID',
  secret: 'SECRET',
});

const params = {
  telemetry_id: "026ac93b-8cdf-4fcb-bfa6-36a31cfecac1",
};

client.fraud.fingerprint.lookup(params)
  .then(resp => { console.log(resp) })
  .catch(err => { console.log(err) });

RESPONSE

{
	"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": [...],
		"rule_match_type": "",
		"rule_match_identifier": ""
	}
}