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>.csidefd.com/client.js"
  referrerpolicy="origin"
  data-src="6">
</script>

Submit fingerprinting data and receive a token

Once the script has loaded, a global sendClientTelemetry function becomes available. Call it to submit the fingerprinting payload and receive a token from the /client API. Both parameters are optional - you can omit either or both.

// With both parameters (both are optional - omit either or both)
const fingerprintResponse = await sendClientTelemetry(
  "your-customer-id",
  "your-transaction-id",
);

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

const result = fingerprintResponse
  ? await fingerprintResponse.json()
  : null;

Parameters

Parameter	Type	Required	Description
`customerId`	`string`	No	Your client customer identifier.
`transactionId`	`string`	No	A unique identifier for the event, transaction, or session you want to associate with this fingerprint.

Return value

The function returns the HTTP response from the /client API. Parse the JSON body to retrieve the 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://api.cside.com/token/v1/client

Example request

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

const response = await fetch("https://api.cside.com/token/v1/client", {
  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 in the `/client` response body after calling `sendClientTelemetry`.

Backend exchange options

Your backend can forward the raw token to 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 token, it returns 404.

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

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