> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest Client Sessions with Device Fingerprinting

> Ingest client sessions with device fingerprinting and IP geolocation data for fraud detection and compliance monitoring.

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](https://api.corsa.finance/api-spec.json) (requires API credentials).

<Note>Before ingesting sessions, make sure the related clients have already been ingested. See the [Ingesting Clients](/api/ingesting-clients) guide.</Note>

***

## 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`

<CodeGroup>
  ```json REST API theme={null}
  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"
  }
  ```

  ```typescript Javascript theme={null}
  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",
  });
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### 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 |

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

***

## 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.

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/clients/123e4567-e89b-12d3-a456-426614174000/sessions
  ```

  ```typescript Javascript theme={null}
  const sessions = await corsa.sessions.getClientSessions(
    "123e4567-e89b-12d3-a456-426614174000"
  );
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

***

## Step 3: End a Session

**Endpoint:** `PUT /v1/sessions/{id}`

Mark a session as ended by providing the `endedAt` timestamp.

<CodeGroup>
  ```json REST API theme={null}
  PUT /v1/sessions/session-uuid
  Content-Type: application/json

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

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

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Ingest Operations" icon="arrow-right-arrow-left" href="/api/ingesting-operations">
    Ingest deposits, withdrawals, and trades for your clients.
  </Card>

  <Card title="Manage Attachments" icon="paperclip" href="/api/managing-attachments">
    Upload and manage files across entities.
  </Card>
</CardGroup>