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 exchange that session token with https://api.cside.com/token/v2/verify to retrieve fingerprint, 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 sends that session token to https://api.cside.com/token/v2/verify with a server-side fingerprint API key.

Using sendClientTelemetry

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

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

const { token: sessionToken } = result;

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

Generate a backend API key

Generate a fingerprint API key in the cside dashboard before calling the authenticated endpoint. The key starts with cside_tgatv1_, is shown only once, and must be stored in your backend secrets manager.

The API key is a team-scoped backend credential. Do not send it to the browser, expose it in frontend bundles, or write it into HTML from a Worker.

API retrieval with the session token

The session token does not contain the full fingerprint payload. Use it as a lookup token from your backend with the authenticated cside endpoint.

Use /token/v2/verify when you need the full JSON payload from a server-to-server integration.

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

The endpoint returns 202 Accepted with { "status": "pending" } while the evaluation is still processing. It returns 200 OK with the completed payload once enrichment has finished.

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: sessionToken }),
});

const datapoints = await csideResponse.json();

if (!csideResponse.ok) {
  throw new Error(datapoints.error_message || "Fingerprint lookup failed.");
}

The completed response includes 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.

Retrieve previous evaluations for the same device

Use /token/v2/device/entries when you need completed evaluations associated with the same device ID as the session token. This is useful for account risk scoring, fraud review queues, abuse investigation, and linking a new session to recent activity from the same browser fingerprint.

The endpoint uses the same backend-only fingerprint API key as /token/v2/verify. It returns results newest first and supports pagination with limit and offset.

curl https://api.cside.com/token/v2/device/entries \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "token": "'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'",
    "limit": 100,
    "offset": 0
  }'

Request body

Field	Type	Required	Description
token	string	Yes	Session token returned by sendClientTelemetry.
limit	number	No	Maximum number of entries to return. Defaults to 500 and is capped at 500.
offset	number	No	Number of entries to skip from the newest result. Defaults to 0. Use the previous response’s next_offset to request the next page.

Response body

The response contains the resolved device_id, an entries array, and pagination metadata. Each entry uses the same flat payload shape as /token/v2/verify.

{
  "device_id": "a1b2c3d4e5f6...",
  "entries": [
    {
      "status": "completed",
      "created_at": 1779441600000,
      "updated_at": 1779441600000,
      "fingerprint": {},
      "network_client_metrics": {}
    }
  ],
  "limit": 100,
  "offset": 0,
  "next_offset": 100,
  "has_more": true
}

Field	Type	Description
device_id	string	Device ID resolved from the session token.
entries	array	Completed evaluations for that device ID, ordered newest first.
limit	number	Effective page size after server-side clamping.
offset	number	Offset used for this response.
next_offset	number | null	Offset to send on the next request. null means there are no more entries.
has_more	boolean	true when another page is available.

Backend example

Use next_offset from the response rather than calculating offsets yourself. Stop when has_more is false.

async function fetchDeviceEntries(sessionToken) {
  const entries = [];
  let offset = 0;
  const limit = 100;

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

    const page = await response.json();

    if (!response.ok) {
      throw new Error(page.error || "Device entries lookup failed.");
    }

    entries.push(...page.entries);
    offset = page.has_more ? page.next_offset : null;
  }

  return entries;
}

If you only need the first page, omit limit and offset. The API returns up to 500 completed evaluations by default.

Public token endpoints

/token/v1/client and /token/v1/clientId remain available for integrations that specifically need the unauthenticated public lookup flow.

Use /token/v1/client when you need the public JSON payload without API-key authentication.

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"

For /token/v1/*, send the raw session token in the request body and do not wrap it in JSON. The clientId endpoint returns plain text. If no fingerprint ID exists for the session token, it returns 404.

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.