POST /v1/identify

Identify a device and get a stable visitor ID.

Endpoint

text
POST https://api.fingerprintiq.com/v1/identify

The JavaScript SDK calls this endpoint automatically. You only need to call it directly if you're building a custom SDK or integrating without the official package.

Request

Headers

Content-Type string required

Must be application/json.

X-API-Key string required

Your API key. See Authentication for details.

Body

signals object required

Object containing all collected client-side signals. Each signal is a SignalResult with a value and duration (collection time in ms). See Signal Types Reference for the full schema.

timestamp number required

Unix timestamp in milliseconds when signal collection began on the client.

url string

The page URL where identification occurred. Used for analytics and domain allowlist verification.

referrer string

The referring page URL, if available.

tag object

Arbitrary key-value metadata to attach to this identification event. Stored with the event and returned via the Server API. Useful for associating a fingerprint with session context (e.g., { "page": "checkout", "experiment": "v2" }).

linkedId string

A string identifier to associate with this event — typically an authenticated user ID, session ID, or order ID. Enables querying all events linked to a specific user via the Server API.

bash
curl -X POST https://api.fingerprintiq.com/v1/identify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fiq_live_your_api_key" \
  -d '{
    "signals": {
      "canvas": { "value": { "hash": "a3f2b1c4...", "isFarbled": false }, "duration": 12.5 },
      "webgl": { "value": { "renderer": "ANGLE (Apple, ANGLE Metal Renderer: Apple M1 Max)", "vendor": "Google Inc. (Apple)" }, "duration": 3.2 },
      "audio": { "value": { "hash": "d4e5f6...", "sampleRate": 44100 }, "duration": 45.0 },
      "navigator": { "value": { "hardwareConcurrency": 8, "platform": "MacIntel", "languages": ["en-US"] }, "duration": 0.1 }
    },
    "timestamp": 1712000000000,
    "url": "https://yoursite.com/checkout",
    "referrer": "https://yoursite.com/"
  }'

javascript
import FingerprintIQ from '@fingerprintiq/js';

const fiq = new FingerprintIQ({ apiKey: 'fiq_live_your_api_key' });
const result = await fiq.identify({
  tag: { page: 'checkout' },
  linkedId: 'user_123',
});
// The SDK builds and sends the full payload automatically

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
}

json
{
  "error": "Invalid or missing API key"
}

json
{
  "error": "Monthly API call limit exceeded",
  "usage": 10001,
  "limit": 10000
}

Response Fields

The identify endpoint returns a compact response — verdicts and top-level scores only. Raw signal data (all 41 client signals plus full server signals) is available server-side via GET /v1/events/:requestId. See the Events API reference.

requestId string

Unique identifier for this specific identification event, in the format req_<ulid>. Pass this to your backend and use it to retrieve full signal data via the Server API.

visitorId string

Stable device identifier in the format iq_<ulid>. This is the primary output — store it to link future visits to the same device.

confidence number

Signal confidence score from 0.0 to 1.0. Low values indicate that many signals failed to collect, which may itself indicate a bot or privacy tool. Scores below 0.7 warrant extra scrutiny.

botProbability number

Bot likelihood score from 0.0 to 1.0. Combines datacenter ASN, headless markers, software renderer, API tampering, and UA/TLS mismatch indicators.

suspectScore number

Composite risk score from 0 to 100. Higher values indicate more risk signals. Combines bot probability, VPN/proxy detection, incognito mode, tampering, and high-activity flags into a single actionable number.

visitCount number

Total number of times this device has been identified. A value of 1 means first-time visitor.

firstSeenAt number

Unix timestamp (milliseconds) of the first identification for this device.

lastSeenAt number

Unix timestamp (milliseconds) of the most recent identification for this device prior to this event.

verdicts object

Per-signal boolean verdicts for this visit.

ip string

The client's IP address as seen by the edge worker.

ipLocation object

Geolocation derived from the IP address: country (ISO 3166-1 alpha-2), city, region, latitude, longitude.

riskFactors string[]

Active risk indicators for this visit. Possible values include:

  • HEADLESS_BROWSER — WebDriver or automation markers detected
  • SOFTWARE_RENDERER — SwiftShader or LLVMpipe GPU
  • TOR_EXIT_NODE — Traffic from Tor network
  • DATACENTER_ASN — Traffic from cloud provider
  • UA_TLS_MISMATCH — User-Agent inconsistent with TLS fingerprint
  • LOW_RTT_COHERENCE — Geo coherence below 0.3 (likely VPN)
timestamp number

Unix timestamp (milliseconds) of this specific identification event.

Error Responses

StatusMeaning
400Invalid JSON body or missing required signals field
401Invalid or missing X-API-Key header
429Rate limit or monthly quota exceeded
500Internal server error — retry with exponential backoff
Previous Authentication
Next GET /v1/demo/visits/:visitorId
Ask a question... ⌘I