Events API | cside docs

This guide walks you through integrating the cside fingerprinting Events API end-to-end: loading the client script, generating an identification 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>.csidetm.com/script.js"
  referrerpolicy="origin"
  data-src="6">
</script>

Generate an identification token

Once the script has loaded, a global function becomes available. Call it with a client identifier (e.g. a clientId or userId) to generate a token.

const result = await submitFingerprint("your-client-id");

Parameters

Parameter	Type	Description
`clientId`	`string`	A unique identifier for the user or session, such as a `clientId` or `userId`.

Return value

The function returns a token object:

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

Send the token to your backend

Pass the returned token to your backend for server-side verification. Your backend endpoint URL will be provided after deployment.

Placeholder URL

Replace the URL below with your actual backend endpoint once it has been provisioned.

POST https://<YOUR_BACKEND_HOST>/<PLACEHOLDER_PATH>

Example request

const response = await fetch("https://<YOUR_BACKEND_HOST>/<PLACEHOLDER_PATH>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: result.token }),
});

const data = await response.json();

Request body

Field	Type	Description
`token`	`string`	The token returned from the client-side `submitFingerprint` call.

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

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

Boolean and string signals indicating suspicious or notable visitor attributes.

Field	Type	Description
`bot`	`string`	Bot detection result. `"not_detected"` when no bot is found.
`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.

`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": "not_detected",
  "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,
  "raw_device_attributes": {
    "math": "5f030fa7d2e5f9f757bfaf81642eb1a6",
    "vendor": "Google Inc."
  }
}