PAM Integration — Overview

This section is the technical contract for connecting a Player Account Management (PAM) system — or any operator backend — to PlaylogiQ.

The integration is inbound only: the PAM pushes player activity into PlaylogiQ in real time, and PlaylogiQ turns that stream into CRM, analytics, lifecycle, segmentation, and gamification. PlaylogiQ does not require any synchronous call back to the PAM to function.

The mental model

                 x-api-key (brand-pinned)
   ┌─────────┐   POST /api/v1/events     ┌──────────────┐    ┌────────────┐
   │   PAM   │ ────────────────────────► │  PlaylogiQ   │──► │  Worker    │
   │ backend │   raw events (your shape) │  ingestion   │    │ derivation │
   └─────────┘                           └──────────────┘    └────────────┘
                                                │                   │
                                    per-brand mapping        stats, lifecycle,
                                    (your shape → canonical)  segments, journeys

1. The PAM authenticates with a brand-scoped API key (one key = one brand).
2. It POSTs events — in its own raw shape — to /api/v1/events.
3. PlaylogiQ applies the brand’s configurable mapping to translate each raw event into the canonical model, always keeping the raw payload.
4. A background worker derives financial stats, advances lifecycle stages, recomputes segments, and runs journeys off the canonical stream.

The three questions the integration answers

The whole contract comes down to how, what, and when the PAM sends.

How — transport & auth

• HTTPS POST to /api/v1/events with a JSON body.
• Header x-api-key: plq_… — a brand-pinned key. The key is the brand boundary: every event it carries is attributed to that brand, and no other.
• Least-privilege: an ingestion key holds only the events:write scope.

See Authentication & API keys.

What — the payload

• One event, or a batch of up to 100, per request.
• Each event needs a player identifier (player_id — your internal id) and an event type (event_type — whatever string your PAM uses). The payload is a free-form JSON object.
• You send your own shape. You do not pre-translate to PlaylogiQ’s model — that is what the mapping engine is for.

See Event ingestion API.

When — timing & delivery semantics

• Real time. Push each event as it happens (or micro-batch every few seconds). PlaylogiQ is built for a continuous stream, not nightly dumps.
• At-least-once is fine. Send an event_id (your idempotency key) and re-sends are safely de-duplicated — so you can retry on network errors without creating duplicates.
• Order-tolerant. Events are stored append-only with their timestamps; derivation does not require strict ordering. Include a timestamp when the event’s real time differs from when you send it (e.g. replays/backfills).

Zero back-and-forth

You never have to ask the PlaylogiQ team to “add an event type” or “support a field”. Everything the PAM sends is mapped by the operator, per brand, in the dashboard — with a live tester that shows exactly what ingestion will produce for a given raw payload before you go live. See Mapping engine.

What’s next

• Authentication & API keys — issue a brand-pinned key, scopes, rotation.
• Event ingestion API — the POST /events contract, batching, idempotency, responses.
• Mapping engine — translate your raw events to canonical, per brand, with transforms and a tester.
• Recipes & scenarios — end-to-end examples (registration, deposits in cents, KYC, status changes, backfill, retries…).
• Canonical event catalog — the event types and payload fields PlaylogiQ consumes.
• Outbound webhooks — optional signed callbacks from PlaylogiQ to your systems.