Quick Start

1. Get Your API Key

Sign up at fingerprintiq.com and create an API key from the dashboard.

Use a fiq_test_ key during development. Test keys have the same full functionality but are excluded from your monthly quota.

2. Install the SDK

npm install @fingerprintiq/js

yarn add @fingerprintiq/js

pnpm add @fingerprintiq/js

<script src="https://cdn.fingerprintiq.com/v1/fiq.min.js"></script>

This guide covers Identify (@fingerprintiq/js), the browser fingerprinting product. If you want server-side caller classification, see the Sentinel guide (@fingerprintiq/server). For CLI and agent analytics, see the Pulse guide (@fingerprintiq/pulse).

3. Identify a Visitor

javascript
import FingerprintIQ from '@fingerprintiq/js';

const fiq = new FingerprintIQ({
  apiKey: 'fiq_live_your_api_key_here',
});

const result = await fiq.identify({
  tag: { page: 'checkout' },
  linkedId: 'user_123',
});

console.log(result.visitorId);      // "iq_01hns3k6tez83695a6t714s6n1"
console.log(result.requestId);      // "req_01hns3k6tez83695a6t7"
console.log(result.confidence);     // 1.0
console.log(result.botProbability); // 0.05
console.log(result.suspectScore);   // 0
console.log(result.visitCount);     // 3

The SDK collects all 41 client signals in parallel before sending a single request. The edge worker adds server-side signals (JA4 TLS fingerprint, ASN, RTT) before computing the visitor ID. Total collection time is typically 50–150 ms depending on device speed.

4. Inspect the Response

json
{
  "requestId": "req_01hns3k6tez83695a6t7",
  "visitorId": "iq_01hns3k6tez83695a6t714s6n1",
  "confidence": 1.0,
  "botProbability": 0.05,
  "suspectScore": 0,
  "visitCount": 3,
  "firstSeenAt": 1712000000000,
  "lastSeenAt": 1712200000000,
  "riskFactors": [],
  "verdicts": {
    "bot": { "result": false, "probability": 0.05 },
    "vpn": { "result": false, "confidence": 0.92 },
    "tor": { "result": false },
    "proxy": { "result": false },
    "incognito": { "result": false },
    "tampering": { "result": false, "anomalyScore": 0 },
    "headless": { "result": false },
    "virtualMachine": { "result": false },
    "devtools": { "result": false },
    "privacyBrowser": { "result": false, "name": null },
    "highActivity": { "result": false },
    "ipBlocklist": { "result": false }
  },
  "ip": "203.0.113.42",
  "ipLocation": { "country": "US", "city": "New York", "region": "NY", "latitude": 40.71, "longitude": -74.01 },
  "timestamp": 1712000003000
}

The same visitorId persists across sessions, incognito mode, cookie clearing, and IP changes. Try it on the live demo.

5. Verify Server-Side (Recommended)

After identifying on the client, pass the requestId to your backend and look up the full event via the Server API. This gives you complete signal data and prevents client-side spoofing.

typescript
// Your backend (Node.js, Hono, Next.js API route, etc.)
const res = await fetch(
  `https://api.fingerprintiq.com/v1/events/${result.requestId}`,
  { headers: { 'Authorization': 'Bearer fiq_secret_your_key' } }
);
const event = await res.json();
// Full signals available in event.signals.client and event.signals.server

const isLegitimate =
  event.confidence >= 0.8 &&
  event.botProbability < 0.3 &&
  !event.verdicts.bot.result;

Never make trust decisions based solely on client-side data. Always verify the visitorId on your server before granting access or taking action.

Next Steps