Events API | cside docs

This guide walks you through integrating the cside fingerprinting Events API end-to-end: loading the client script, generating a session token, sending it to your backend, and interpreting the response payload.

Integration flow

Add the script to your page

Include the cside fingerprinting script in your page’s <head>. It should be loaded before you call any fingerprinting functions.

<script
  src="https://<YOUR_SUBDOMAIN>.csidefd.com/client.js"
  referrerpolicy="origin"
  data-src="6">
</script>

Submit telemetry and receive a session token

Once the script has loaded, a global sendClientTelemetry function becomes available. Loading the script does not create a session fingerprint by itself. Call sendClientTelemetry(externalIds?) to submit telemetry to /client and receive a session token. Pass an optional externalIds object if you want to attach your own identifiers.

const result = await sendClientTelemetry({
  email: "user@example.com",
  accountId: "1234567890",
});

// Or call with no arguments
// const result = await sendClientTelemetry();

if (result.errors) {
  console.error(result.errors);
  throw new Error("Telemetry request failed.");
}

const token = result.token;

Parameters

Parameter	Type	Required	Description
`externalIds`	`Record<string, string>`	No	Optional identifiers you want attached to the fingerprint, such as `accountId`, `orderId`, or `email`.

To receive the throwawayEmail signal, pass the email address in this object using the key email.

Return value

The function returns a JSON object (already parsed, so you do not need to call .json() on it):

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

The token field holds the fingerprint session token. If telemetry collection runs into problems, the object also includes an optional errors array you can log. Extract result.token and send only that session token string to your backend.

Retrieve fingerprint data from your backend

Generate a backend-only fingerprint API key in the cside dashboard, store it as a server-side secret, and use it to exchange the session token with cside. The API key is shown only once and must not be exposed in browser code.

if (!token) {
  throw new Error("Fingerprint session token was not returned.");
}

const response = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token }),
});

const data = await response.json();

Request body

Send JSON in the shape { "token": "<session token>" }, where the value is result.token from the previous step.

Token lookup options

Use the authenticated endpoint for production server-to-server exchanges. The public endpoints are still available when an integration specifically needs the unauthenticated lookup flow.

Endpoint	Response	Use when
`/token/v2/verify`	JSON	You need authenticated backend retrieval with a fingerprint API key.
`/token/v2/device/entries`	JSON	You need completed evaluations for the same device ID as a session token.
`/token/v1/client`	JSON	You need the public fingerprinting response payload.
`/token/v1/clientId`	Plain text	You only need the stable fingerprint ID from the public lookup flow.

/token/v2/verify returns 202 Accepted with { "status": "pending" } while processing, then 200 OK with the completed payload. /token/v2/device/entries accepts { "token": "...", "limit": 100, "offset": 0 } and returns { "device_id": "...", "entries": [...], "next_offset": 100, "has_more": true }, where each entry uses the /token/v2/verify response shape. limit is optional, defaults to 500, and is capped at 500. The clientId endpoint returns only the fingerprint unique ID as plain text. If no fingerprint unique ID exists for the session token, it returns 404.

Example backend request

const csideResponse = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token }),
});

const data = await csideResponse.json();

Interpret the backend response

Your backend returns a JSON response containing the identification result and associated signals. See the full response reference below.

Response reference

This response reference applies to /token/v1/client. The authenticated /token/v2/verify endpoint returns a flat JSON payload with status, created_at, updated_at, and any available enrichment fields, such as vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics, and fingerprint_enrichment. The authenticated /token/v2/device/entries endpoint returns a device_id, an entries array containing those same flat payloads for completed evaluations associated with that device ID, and pagination fields such as limit, offset, next_offset, and has_more.

The backend response includes visitor identification, browser details, IP intelligence, and a suite of fraud-detection signals.

Top-level fields

Field	Type	Description
`linked_id`	`string`	An identifier you associated with this visitor.
`tags`	`object`	Custom metadata attached to the event.
`timestamp`	`number`	Unix timestamp (milliseconds) of the event.
`event_id`	`string`	Unique identifier for this fingerprinting event.
`url`	`string`	The page URL where the fingerprint was collected.
`ip_address`	`string`	The visitor’s IP address.
`user_agent`	`string`	The raw User-Agent string from the visitor’s browser.
`client_referrer`	`string`	The referrer URL of the page.

`browser_details`

Details about the visitor’s browser and operating system.

Field	Type	Description
`browser_name`	`string`	Browser name (e.g. `"Chrome"`).
`browser_major_version`	`string`	Major version number.
`browser_full_version`	`string`	Full version string.
`os`	`string`	Operating system name.
`os_version`	`string`	Operating system version.
`device`	`string`	Device type (e.g. `"Other"`, `"Mobile"`).

`identification`

The primary identification result for the visitor.

Field	Type	Description
`visitor_id`	`string`	A stable, unique identifier for this visitor.
`confidence.score`	`number`	Confidence score between `0` and `1`.
`confidence.version`	`string`	Version of the confidence model used.
`visitor_found`	`boolean`	Whether this visitor has been seen before.
`first_seen_at`	`number`	Unix timestamp (ms) of the visitor’s first identification.
`last_seen_at`	`number`	Unix timestamp (ms) of the visitor’s most recent identification.

`supplementary_id_high_recall`

A secondary identification optimised for higher recall (fewer false negatives) at the cost of slightly lower precision.

Field	Type	Description
`visitor_id`	`string`	Visitor identifier under the high-recall model.
`visitor_found`	`boolean`	Whether this visitor was found.
`confidence.score`	`number`	Confidence score between `0` and `1`.
`confidence.version`	`string`	Version of the confidence model used.
`first_seen_at`	`number`	Unix timestamp (ms) of first identification.
`last_seen_at`	`number`	Unix timestamp (ms) of most recent identification.

`proximity`

Geolocation proximity data for the visitor.

Field	Type	Description
`id`	`string`	Proximity location identifier.
`precision_radius`	`number`	Precision radius in kilometres.
`confidence`	`number`	Confidence score for the proximity estimate.

`ip_info`

IP address information for the visitor.

Field	Type	Description
`v4.address`	`string`	IPv4 address.
`v6.address`	`string`	IPv6 address.

`ip_blocklist`

Whether the visitor’s IP appears on known blocklists.

Field	Type	Description
`email_spam`	`boolean`	IP is associated with email spam.
`attack_source`	`boolean`	IP is a known attack source.
`tor_node`	`boolean`	IP is a Tor exit node.

Fraud & environment signals

Signals indicating suspicious or notable visitor attributes.

Field	Type	Description
`bot.result`	`string`	Bot detection result. Use `"detected"` or `"not_detected"`.
`bot.score`	`number`	Bot detection score.
`bot.signal`	`string[]`	Signals that contributed to the bot detection result.
`root_apps`	`boolean`	Device has root/superuser apps installed.
`emulator`	`boolean`	Device is an emulator.
`proxy`	`boolean`	Visitor is using a proxy.
`proxy_confidence`	`string`	Confidence level: `"low"`, `"medium"`, or `"high"`.
`vpn`	`boolean`	Visitor is using a VPN.
`vpn_confidence`	`string`	Confidence level: `"low"`, `"medium"`, or `"high"`.
`incognito`	`boolean`	Browser is in incognito/private mode.
`tampering`	`boolean`	Browser attributes have been tampered with.
`jailbroken`	`boolean`	Device is jailbroken.
`frida`	`boolean`	Frida instrumentation toolkit detected.
`virtual_machine`	`boolean`	Visitor is running in a virtual machine.
`developer_tools`	`boolean`	Browser developer tools are open.
`mitm_attack`	`boolean`	Man-in-the-middle attack detected.
`replayed`	`boolean`	The request is a replay of a previous request.
`high_activity_device`	`boolean`	Unusually high number of identifications from this device.
`throwawayEmail`	`boolean`	`true` when the submitted `email` identifier is a disposable or throwaway email address.

`raw_device_attributes`

Low-level browser fingerprint components.

Field	Type	Description
`math`	`string`	Hash of math engine output.
`vendor`	`string`	GPU/graphics vendor string.

Full response example

{
  "linked_id": "somelinkedId",
  "tags": {},
  "timestamp": 1708102555327,
  "event_id": "1708102555327.NLOjmg",
  "url": "http://www.example.com/login",
  "ip_address": "61.127.217.15",
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...",
  "client_referrer": "https://example.com/blog/my-article",
  "browser_details": {
    "browser_name": "Chrome",
    "browser_major_version": "74",
    "browser_full_version": "74.0.3729",
    "os": "Windows",
    "os_version": "7",
    "device": "Other"
  },
  "identification": {
    "visitor_id": "Ibk1527CUFmcnjLwIs4A9",
    "confidence": { "score": 0.97, "version": "1.1" },
    "visitor_found": false,
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "supplementary_id_high_recall": {
    "visitor_id": "3HNey93AkBW6CRbxV6xP",
    "visitor_found": true,
    "confidence": { "score": 0.97, "version": "1.1" },
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "proximity": {
    "id": "w1aTfd4MCvl",
    "precision_radius": 10,
    "confidence": 0.95
  },
  "bot": {
    "result": "not_detected",
    "score": 0,
    "signal": []
  },
  "root_apps": false,
  "emulator": false,
  "ip_info": {
    "v4": { "address": "94.142.239.124" },
    "v6": { "address": "2001:db8:3333:4444:5555:6666:7777:8888" }
  },
  "ip_blocklist": {
    "email_spam": false,
    "attack_source": false,
    "tor_node": false
  },
  "proxy": true,
  "proxy_confidence": "low",
  "vpn": false,
  "vpn_confidence": "high",
  "incognito": false,
  "tampering": false,
  "jailbroken": false,
  "frida": false,
  "virtual_machine": false,
  "developer_tools": false,
  "mitm_attack": false,
  "replayed": false,
  "high_activity_device": false,
  "throwawayEmail": false,
  "raw_device_attributes": {
    "math": "5f030fa7d2e5f9f757bfaf81642eb1a6",
    "vendor": "Google Inc."
  }
}