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.

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"
  },
  "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",
  },
  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",
        },
        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
`referenceId`	No	Your external session reference ID
`startedAt`	No	Session start time (defaults to current time)

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()

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 Type Values

Step 2: Retrieve Sessions for a Client

Step 3: End a Session

What’s Next?

Ingest Operations

Manage Attachments

​Overview

​Step 1: Create a Session

​Key Fields

​Device Type Values

​Step 2: Retrieve Sessions for a Client

​Step 3: End a Session

​What’s Next?

Ingest Operations

Manage Attachments

Overview

Step 1: Create a Session

Key Fields

Device Type Values

Step 2: Retrieve Sessions for a Client

Step 3: End a Session

What’s Next?