Every integration sends data to UMAP360 through a single endpoint: POST /v1-batch. You send a JSON batch of events, authenticated with a write key, and the platform resolves identity, computes attribution, and evaluates engagement rules for you.

The endpoint

POST https://YOUR_PROJECT_REF.supabase.co/functions/v1/v1-batch
Authorization: Bearer uk_live_YOUR_WRITE_KEY
Content-Type: application/json

The request body is a single object with a batch array of events:

{ "batch": [ /* 1–100 event objects */ ] }

Content-Type must be application/json — any other value is rejected with 400. Ingestion requires a write key (uk_live_); an admin key also works, but a read key returns 403.

A complete request

curl -X POST https://YOUR_PROJECT_REF.supabase.co/functions/v1/v1-batch \
  -H "Authorization: Bearer uk_live_YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "type": "track",
        "event": "Purchase Completed",
        "messageId": "msg_abc123",
        "timestamp": "2026-02-28T10:00:00.000Z",
        "anonymousId": "anon_xyz789",
        "userId": "user_456",
        "properties": {
          "order_id": "ORD-123",
          "total": 4999,
          "currency": "INR"
        },
        "context": {
          "page": { "url": "https://example.com/checkout", "path": "/checkout" },
          "campaign": { "source": "google", "medium": "cpc", "gclid": "abc123" }
        }
      }
    ]
  }'

Event schema

Every event is a JSON object. Four fields are required on every event, regardless of type — if any is missing, that event is rejected (the rest of the batch still processes):

The remaining fields are conditional or optional:

Event types

How event names are stored

track events are stored under the name you send in event. The other types are stored under a system name, which is what you'll see in the dashboard and the Profiles API:

The context object

context is free-form JSON and is stored largely as-sent alongside the event — the server never validates or rejects an event for its context contents. It makes two changes on the way in: it adds a server-derived ip_address, and it strips context.fingerprint when consent is absent (see below). UMAP360 recognises the following fields for attribution and identity:

interface Context {
  page?:     { url?: string; path?: string; title?: string; referrer?: string;
               search?: string; hash?: string; language?: string };
  campaign?: { source?: string; medium?: string; name?: string; term?: string; content?: string;
               // click IDs fed to the offline-conversion (Google / Meta CAPI) pipeline:
               gclid?: string; fbclid?: string; ttclid?: string; msclkid?: string; li_fat_id?: string;
               gbraid?: string; wbraid?: string; twclid?: string; igshid?: string;
               epik?: string; dclid?: string; rdt_cid?: string; gad_source?: string;
               referrer_chain?: { url: string; timestamp: string }[] };
  device?:   { id?: string; type?: string; manufacturer?: string; model?: string; uaClientHints?: object };
  browser?:  { name?: string; version?: string };
  os?:       { name?: string; version?: string };
  screen?:   { width?: number; height?: number; density?: number;
               viewport?: { innerWidth?: number; innerHeight?: number } };
  network?:  { online?: boolean; wifi?: boolean; cellular?: boolean; saveData?: boolean };
  session?:  { id?: string; started_at?: string; page_views?: number;
               events_count?: number; is_new_session?: boolean };
  fingerprint?: { hash?: string; components?: object };
  consent?:  boolean | { fingerprinting?: boolean; identity?: boolean; analytics?: boolean };
  gpc?: boolean;                       // Global Privacy Control signal, when asserted
  locale?: string;
  timezone?: string;
  timezone_offset_mins?: number;
  app?:     { name?: string; version?: string; build?: string; namespace?: string };
  library?: { name?: string; version?: string };
  user_agent?: string;
}

The Web SDK populates all of these for you; direct-REST integrators send whatever subset they have.

Click-ID fields under campaign (gclid, fbclid, …) are associated with the visitor's profile and used by the offline-conversion pipeline (Google / Meta CAPI), which reads each profile's stored click-IDs.

The response

A request that passes authentication, batch-shape validation, rate limits, and your plan's event quota returns 200 OK. The body reports how many events were accepted:

{ "success": true, "processed": 1, "failed": 0, "duration_ms": 45 }

If some events in the batch fail validation or processing, the request is still 200 — success flips to false and a per-event errors array lists the first ten failures, each as "<messageId>: <reason>":

{
  "success": false,
  "processed": 8,
  "failed": 2,
  "errors": [
    "msg_abc: messageId is required",
    "msg_def: event name is required for track events"
  ],
  "duration_ms": 120
}

An empty batch ({ "batch": [] }) is accepted and returns { "success": true, "processed": 0, "failed": 0, "duration_ms": ... }.

Response headers

Every response carries X-Request-ID (your value echoed back, or a server-minted one — useful for support correlation), API-Version: 1, X-Content-Type-Options: nosniff, and Referrer-Policy: no-referrer — see Response headers. While your org is in a billing grace period, a successful 200 also carries X-UMAP360-Quota-Status: grace (exposed via Access-Control-Expose-Headers, so cross-origin JS can read it); an active org sends no such header.

Batch limits

The 1 MiB cap is enforced twice, so a request with a missing or understated Content-Length can't slip past it: first as a fast pre-auth check on the Content-Length header, then again while the body is read — the parser streams and aborts at the ceiling on the actual bytes received. Either way you get the structured 413 shown above. Split large volumes into multiple requests of ≤100 events / ≤1 MiB each — see Event volume.

Next

• Errors & rate limits — every status code, the error envelope, rate limits, and the retry policy.
• Profiles API — read the profiles your events resolve into.
• Consent API — record / read per-purpose consent decisions.
• Authentication — key types and how to keep them safe.

Last updated 2026-06-10