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 fingerprintResponse = await sendClientTelemetry({
  email: "user@example.com",
  accountId: "1234567890",
});

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

if (!fingerprintResponse?.ok) {
  throw new Error("Fingerprint telemetry request failed.");
}

const result = await fingerprintResponse.json();
const sessionToken = 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 the HTTP response from the /client API. Parse the JSON body to retrieve the response object that contains the session token string:

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

Extract result.token as the fingerprint session token in the browser and send only that session token string to your backend.

Retrieve fingerprint data with the session token on your backend

On your backend, use the extracted session token with the cside token endpoint that matches the data you need.

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

const response = await fetch("https://api.cside.com/token/v1/client", {
  method: "POST",
  headers: { "Content-Type": "text/plain" },
  body: sessionToken,
});

const data = await response.json();

Request body

/client returns JSON like { "token": "..." }. Extract result.token as the session token and send that string as the request body. Do not send the whole JSON object.

Token lookup options

You can use the raw session token with the cside fingerprinting service in two ways:

Endpoint	Response	Use when
`/token/v1/client`	JSON	You need the full fingerprinting response payload.
`/token/v1/clientId`	Plain text	You only need the fingerprint unique ID.

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/v1/client", {
  method: "POST",
  headers: { "Content-Type": "text/plain" },
  body: sessionToken,
});

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 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."
  }
}