Guides

About 10 minutes

SEND SERVER-SIDE EVENTS.

Record conversions and behaviour from your own backend, with consent carried on every event and contact details hashed before they leave your server.

events:write

Steps

  1. 1. Get a key

    Workspace admins issue keys in the app at /app/api-keys. Start with a sandbox key: it is bound to a showroom workspace and can never touch live data. Keep the secret server-side.

    export QN_API_KEY="qn_sandbox_…"
    curl "$QN_BASE/me" -H "Authorization: Bearer $QN_API_KEY"
  2. 2. Find the pixel

    Events attach to a PixelBridge pixel in the same workspace as the key. Copy the pixel id from the PixelBridge screen in the app.

  3. 3. Send a batch

    Up to 50 events per call. Every event needs a name, a timestamp and the consent state you captured. Contact details are hashed with SHA-256 before storage, so send them normalised (trimmed, lowercased).

    curl -X POST "$QN_BASE/events" \
      -H "Authorization: Bearer $QN_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "pixel_id": "pxl_…",
        "events": [{
          "event_name": "purchase",
          "occurred_at": "2026-09-13T10:04:00Z",
          "value": 249.00,
          "currency": "AED",
          "consent": { "measurement": true },
          "identity": { "email": "buyer@example.com" }
        }]
      }'
  4. 4. Send the same batch twice

    Reuse the Idempotency-Key. The second call returns the first response instead of double-counting. Use one key per logical batch, not per retry.

Done when

A 202 with accepted and rejected counts, then the event appearing in the next daily rollup at GET /pixel-rollups.