Players API

CRUD + lifecycle for the player CDP.

List players

GET /v1/players?cursor=&limit=50&status=active&email=...

Auth: Clerk session.

Query params:

• cursor — pagination cursor
• limit — 1..200 (default 50)
• status — active | self_excluded | banned | deleted | conflict
• email, external_id, phone, telegram_id — exact match filters

Response:

{
  "data": [
    {
      "id": "uuid",
      "tenant_id": "uuid",
      "project_id": "uuid",
      "external_id": "ext_123",
      "email": "player@example.com",
      "phone": "+15551234567",
      "telegram_id": null,
      "anonymous_ids": ["anon_..."],
      "status": "active",
      "first_seen_at": "...",
      "last_seen_at": "...",
      "total_deposited": 12345,        // cents in tenant base currency
      "total_withdrawn": 5000,
      "total_wagered": 50000,
      "total_won": 47500,
      "ggr": 2500,
      "bet_count": 142,
      "session_count": 25,
      "default_currency_code": "EUR",
      "current_tier_code": "silver",
      "tier_promoted_at": "...",
      "kyc_status": "verified",
      "kyc_level": 2,
      "churn_score": 0.12,
      "ltv_predicted": null,
      "segment_ids": ["uuid", "uuid"],
      "custom_attributes": {},
      "created_at": "...", "updated_at": "...", "deleted_at": null
    }
  ],
  "meta": { "next_cursor": "..." }
}

Get player

GET /v1/players/:id

Same shape as list rows, single object.

Update player

PATCH /v1/players/:id

{
  "email": "new@example.com",
  "phone": "+15559876543",
  "status": "active",
  "custom_attributes": { "source": "facebook" }
}

Computed totals (total_deposited, ggr, etc.) are NOT patchable — they're maintained by stream-processor. Trying to set them is a 422.

Delete (soft)

DELETE /v1/players/:id → sets deleted_at = now(). Player rows + message_sends rows are kept; campaign fan-outs filter WHERE deleted_at IS NULL.

Player tier

See VIP tiers API.

Player KYC

POST /v1/players/:id/kyc/request | approve | revoke — see KYC feature page.

Player segments refresh (admin)

POST /v1/players/:id/refresh-segments — recompute segment membership for one player. Returns the diff:

{
  "data": {
    "player_id": "...",
    "matched_segment_ids": ["uuid", "uuid"],
    "added": ["uuid"],
    "removed": [],
    "total_segments_evaluated": 12,
    "duration_ms": 87
  }
}

Player deposits-daily (charts)

GET /v1/players/:id/deposits-daily → 30-day series:

{
  "data": [
    { "date": "2026-04-08", "amount": 5000 },
    { "date": "2026-04-09", "amount": 0 },
    ...
  ]
}

Amounts are denominated in tenant base currency (DUAL pattern — amount_base from CH).

Player timeline

GET /v1/players/:id/timeline?cursor=&limit=50 → last N events for the player:

{
  "data": [
    {
      "ingestion_id": "uuid",
      "event": "deposit_confirmed",
      "timestamp": "...",
      "properties": { "amount": 5000, "currency": "EUR", ... }
    }
  ],
  "meta": { "next_cursor": "..." }
}

Player messages

GET /v1/players/:id/messages?limit=25 → last N message_sends rows for the player.

Player bonus grants

GET /v1/bonus-grants?player_id=:id&limit=25 — see Bonuses API.