Events ingestion

POST /v1/events — single event. POST /v1/events/batch — up to 100 events per request.

Auth: API key.

Single event

{
  "event": "deposit_confirmed",
  "external_id": "casino_player_001",
  "anonymous_id": "anon_xyz",          // optional
  "timestamp": "2026-05-08T10:00:00Z", // ISO-8601 UTC
  "properties": {
    "amount": 5000,                    // smallest currency unit (cents / sat)
    "currency": "EUR",
    "transaction_id": "tx_abc",
    "payment_method": "card"
  },
  "context": {                          // optional — SDK metadata
    "ip": "1.2.3.4",
    "user_agent": "...",
    "library": { "name": "ucrm-js", "version": "1.0.0" }
  }
}

Response 202:

{
  "data": {
    "ingestion_id": "uuid",   // for idempotency / debugging
    "received_at": "..."
  }
}

202 is intentional — the event is accepted into the queue, not yet processed. Stream-processor consumes within ~50ms typical.

Canonical event names

# Identity / session
signup, login, logout, session_start, session_end, page_view, click

# KYC + responsible gaming
kyc_submitted, kyc_approved, kyc_rejected, kyc_expired, kyc_level_upgraded
self_exclusion_set, self_exclusion_lifted
deposit_limit_set, deposit_limit_reached
loss_limit_set, loss_limit_reached
session_limit_warning, session_limit_exceeded
reality_check, cooldown_entered

# Money in/out
deposit_initiated, deposit_confirmed, deposit_failed
withdrawal_requested, withdrawal_confirmed, withdrawal_failed

# Wagering — casino
bet_placed, bet_won, bet_lost, bet_settled

# Wagering — sportsbook (two-phase)
sport_bet_placed, sport_bet_settled, sport_bet_voided, sport_cashout

# Bonuses
bonus_claimed, bonus_wagered, bonus_completed, bonus_expired

# Outbound messaging delivery feedback
email_sent, email_opened, email_clicked, email_bounced
sms_sent, sms_clicked
push_sent, push_opened

Custom events: prefix with custom_ — UCRM accepts them but doesn't enforce a schema. Use for operator-specific signals (slot_jackpot_won, etc.).

Required properties per event

UCRM validates property shapes via JSON Schema. Key examples:

deposit_confirmed:

{
  "amount": <int>,           // required, smallest unit
  "currency": "<code>",      // required
  "transaction_id": "<str>", // required (idempotency on platform side)
  "payment_method": "<str>"  // optional
}

bet_settled:

{
  "amount": <int>,           // stake
  "payout": <int>,           // 0 if lost
  "currency": "<code>",
  "game_id": "<str>",
  "game_category": "slots | live | table | crash | dice | sports | other",
  "bet_id": "<str>",
  "outcome": "won | lost"
}

sport_bet_placed:

{
  "amount": <int>,
  "currency": "<code>",
  "bet_id": "<str>",
  "sport": "football | basketball | tennis | hockey | mma | ...",
  "bet_type": "single | accumulator | system",
  "odds": "<decimal-string>",
  "event_ref": "<match-id>"
}

sport_bet_settled:

{
  "amount": <int>,
  "payout": <int>,
  "currency": "<code>",
  "bet_id": "<str>",         // matches the placed event
  "outcome": "won | lost"
}

Batch ingestion

POST /v1/events/batch — up to 100 events:

{
  "events": [
    { "event": "...", ... },
    { "event": "...", ... }
  ]
}

Returns per-event ingestion_ids:

{
  "data": {
    "ingested": [
      { "ingestion_id": "uuid", "ok": true },
      { "ingestion_id": null, "ok": false, "error": "EVENT_INVALID" }
    ]
  }
}

Idempotency

Idempotency-Key header (UUID) — replays return the same ingestion_id without reprocessing. Use this when retrying after network errors.

DUAL currency enrichment

After ingestion, stream-processor enriches money events with amount_base + payout_base + base_currency + fx_rate_locked for dashboard queries. See Multi-currency.