Ingest Client Sessions with Device Fingerprinting

This guide walks you through ingesting Client Sessions - records that capture device fingerprints, IP addresses, and geolocation data for each client interaction with your platform. Full API endpoint details are available in the API Reference (requires API credentials).

Before ingesting sessions, make sure the related clients have already been ingested. See the Ingesting Clients guide.

Overview

Sessions allow Corsa to track client device activity for fraud detection and behavioral analysis. Each session captures:

IP address - automatically resolved to geolocation by Corsa
Device fingerprint - unique hash identifying the device
Device metadata - browser, OS, screen resolution, timezone, etc.
Device custom fields - optional key-value metadata attached to the device (merged on upsert by fingerprint)

Step 1: Create a Session

Endpoint: POST /v1/sessions

POST /v1/sessions
Content-Type: application/json

{
"clientId": "123e4567-e89b-12d3-a456-426614174000",
"referenceId": "sess_abc123",
"ipAddress": "203.0.113.42",
"device": {
"fingerprint": "a1b2c3d4e5f6g7h8i9j0",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
"browser": "Chrome",
"browserVersion": "120.0.6099.109",
"os": "macOS",
"osVersion": "14.2.1",
"deviceType": "DESKTOP",
"screenResolution": "1920x1080",
"language": "en-US",
"timezone": "America/New_York",
"customFields": {
"deviceRiskScore": { "label": "Device Risk Score", "value": 72 },
"isEmulator": { "label": "Is Emulator", "value": false }
}
},
"startedAt": "2024-01-15T10:30:00Z"
}

const session = await corsa.sessions.createSession({
  clientId: "123e4567-e89b-12d3-a456-426614174000",
  referenceId: "sess_abc123",
  ipAddress: "203.0.113.42",
  device: {
    fingerprint: "a1b2c3d4e5f6g7h8i9j0",
    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    browser: "Chrome",
    browserVersion: "120.0.6099.109",
    os: "macOS",
    osVersion: "14.2.1",
    deviceType: "DESKTOP",
    screenResolution: "1920x1080",
    language: "en-US",
    timezone: "America/New_York",
    customFields: {
      deviceRiskScore: { label: "Device Risk Score", value: 72 },
      isEmulator: { label: "Is Emulator", value: false },
    },
  },
  startedAt: "2024-01-15T10:30:00Z",
});

from corsa_sdk.api.sessions.create_session import _get_kwargs
from corsa_sdk.models.create_session_dto import CreateSessionDto

resp = http.request(**_get_kwargs(
    body=CreateSessionDto(
        client_id="123e4567-e89b-12d3-a456-426614174000",
        reference_id="sess_abc123",
        ip_address="203.0.113.42",
        device={
            "fingerprint": "a1b2c3d4e5f6g7h8i9j0",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
            "browser": "Chrome",
            "browserVersion": "120.0.6099.109",
            "os": "macOS",
            "osVersion": "14.2.1",
            "deviceType": "DESKTOP",
            "screenResolution": "1920x1080",
            "language": "en-US",
            "timezone": "America/New_York",
            "customFields": {
                "deviceRiskScore": {"label": "Device Risk Score", "value": 72},
                "isEmulator": {"label": "Is Emulator", "value": False},
            },
        },
        started_at="2024-01-15T10:30:00Z",
    ),
))
session = resp.json()

Key Fields

Field	Required	Description
`clientId`	Yes	Corsa client ID or `referenceId` of the client
`ipAddress`	Yes	IPv4 or IPv6 address (auto-resolved to geolocation)
`device`	Yes	Device information object
`device.fingerprint`	Yes	Unique device fingerprint hash
`device.customFields`	No	Key-value custom fields stored on the device (merged on upsert by fingerprint)
`referenceId`	No	Your external session reference ID
`startedAt`	No	Session start time (defaults to current time)

Device custom fields

Send device.customFields as a map of keys to { label, value } objects. Corsa stores custom fields on the device (not the session). When a new session uses a fingerprint that already exists, incoming custom fields are merged with existing values — new keys are added and existing keys are overwritten. The field type is inferred from value (string, number, or boolean), so keep each key’s type consistent across sessions. Subsequent sessions with the same fingerprint can send only the keys you want to update:

{
  "clientId": "123e4567-e89b-12d3-a456-426614174000",
  "ipAddress": "203.0.113.42",
  "device": {
    "fingerprint": "a1b2c3d4e5f6g7h8i9j0",
    "customFields": {
      "deviceRiskScore": { "label": "Device Risk Score", "value": 85 }
    }
  }
}

Device custom fields can be used in transaction monitoring rules under the Device entity (for example, customFields.deviceRiskScore).

Device Type Values

Type	Description
`DESKTOP`	Desktop computer
`MOBILE`	Mobile phone
`TABLET`	Tablet device
`UNKNOWN`	Unidentified device type

Corsa automatically resolves the IP address to geolocation data (country, city, coordinates). You do not need to provide geolocation separately.

Step 2: Retrieve Sessions for a Client

Endpoint: GET /v1/clients/{clientId}/sessions View all sessions associated with a specific client to analyze login patterns and device usage.

GET /v1/clients/123e4567-e89b-12d3-a456-426614174000/sessions

const sessions = await corsa.sessions.getClientSessions(
  "123e4567-e89b-12d3-a456-426614174000",
);

from corsa_sdk.api.sessions.get_client_sessions import _get_kwargs

resp = http.request(**_get_kwargs(
    client_id="123e4567-e89b-12d3-a456-426614174000",
))
sessions = resp.json()

Get a Session by ID

Endpoint: GET /v1/sessions/{id} Retrieve a single session by its Corsa session ID or your referenceId.

GET /v1/sessions/session-uuid

const session = await corsa.sessions.getSession("session-uuid");

from corsa_sdk.api.sessions.get_session import _get_kwargs

resp = http.request(**_get_kwargs(id="session-uuid"))
session = resp.json()

Step 3: End a Session

Endpoint: PUT /v1/sessions/{id} Mark a session as ended by providing the endedAt timestamp.

PUT /v1/sessions/session-uuid
Content-Type: application/json

{
"endedAt": "2024-01-15T12:00:00Z"
}

const updated = await corsa.sessions.updateSession("session-uuid", {
  endedAt: "2024-01-15T12:00:00Z",
});

from corsa_sdk.api.sessions.update_session import _get_kwargs
from corsa_sdk.models.update_session_dto import UpdateSessionDto

resp = http.request(**_get_kwargs(
    id="session-uuid",
    body=UpdateSessionDto(
        ended_at="2024-01-15T12:00:00Z",
    ),
))
updated = resp.json()

Data Ingestion

Ingest Client Sessions with Device Fingerprinting

Overview

Step 1: Create a Session

Key Fields

Device custom fields

Device Type Values

Step 2: Retrieve Sessions for a Client

Get a Session by ID

Step 3: End a Session

What’s Next?

Ingest Operations

Manage Attachments

​Overview

​Step 1: Create a Session

​Key Fields

​Device custom fields

​Device Type Values

​Step 2: Retrieve Sessions for a Client

​Get a Session by ID

​Step 3: End a Session

​What’s Next?

Ingest Operations

Manage Attachments

Overview

Step 1: Create a Session

Key Fields

Device custom fields

Device Type Values

Step 2: Retrieve Sessions for a Client

Get a Session by ID

Step 3: End a Session

What’s Next?