Retrieving datapoints

The browser does not need to know what sendClientTelemetry(externalIds?) sends internally. Call the function, read the returned session token, and let your backend use that session token with https://api.cside.com/token/v1/client or https://api.cside.com/token/v1/clientId to retrieve identification, bot, browser, device, IP, and environment datapoints.

End-to-end flow

1. The browser calls sendClientTelemetry(externalIds?).
2. sendClientTelemetry posts telemetry to the configured CLIENT_URL, usually /client.
3. /client returns JSON in the form { "token": "..." }, where token is the fingerprint session token.
4. Your backend uses that session token with https://api.cside.com/token/v1/client for the full JSON payload or https://api.cside.com/token/v1/clientId for the stable fingerprint ID.

Using sendClientTelemetry

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

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

const { token: sessionToken } = await telemetryResponse.json();

if (!sessionToken) {
  throw new Error("No fingerprint session token returned.");
}

After you extract sessionToken, send it to your backend. Your backend performs the token exchange with cside.

You can also call sendClientTelemetry() with no arguments. Use externalIds only when you want to attach your own identifiers, such as accountId, orderId, or email, to the fingerprint.

Retrieval options

Method	Status	Best for
API	Available	Request-time decisions and backend enrichment
S3 export	Available when enabled	Batch analysis, warehousing, and offline review
Webhook	Planned or account-enabled	Push delivery into internal systems
WebSocket	Planned or account-enabled	Live streams and near-real-time dashboards

API retrieval with the session token

The session token does not contain the full fingerprint payload. Use it directly as a lookup token with the cside token endpoints.

Use /token/v1/client when you need the full JSON payload.

See the Events API response reference for example output from the API call.

curl https://api.cside.com/token/v1/client \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Use /token/v1/clientId when you only need the stable fingerprint ID.

curl https://api.cside.com/token/v1/clientId \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Send the raw session token in the request body. Do not wrap the session token in JSON.

The clientId endpoint returns plain text. If no fingerprint 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 datapoints = await csideResponse.json();

Use /token/v1/clientId when you only need a stable fingerprint ID for storage or joins. Use /token/v1/client when you need the full datapoint bundle for decisions.

S3 export

cside can export fingerprint records to S3 when fingerprint S3 export is configured for a domain. Use this for batch workflows where you do not need a request-time decision.

Exported records include the transaction ID, customer domain, timestamp, customer reference, and fingerprint identifier.

Webhooks

Webhook delivery is planned or enabled for selected accounts. Use webhooks when your system should receive new datapoints without polling the API.

Good webhook use cases include:

• Sending fingerprint events to a fraud queue
• Enriching a SIEM or data pipeline
• Triggering review workflows for suspicious sessions

WebSocket streams

WebSocket delivery is planned or enabled for selected accounts. Use it when you need a live feed for dashboards, operations tools, or active investigation workflows.