Send events via Upstack Conversion API

Upstack Conversion API (CAPI) — send tracking events from your server. They join the same pipeline as browser pixel events: identity resolution, enrichment, analytics, and destination forwarding.

Always send an array of events, even for one. Each event needs a name; everything else is optional. Extra keys are accepted and passed through.

Send ipAddress, userAgent and locale yourself. The API uses only what’s in the body — it never fills these in from the request connection or headers — and they drive match quality at your destinations.

eventId is your idempotency key. Optional, but strongly recommended: send the same eventId again within 30 days and the duplicate is skipped, so retries and webhook loops are safe. When the browser Pixel fires the same conversion, send the same eventId (and identityId) from both so they count as one event rather than two.

Limits. 100 events per request, 128 KB per body, and 100 items per trait or address array. Individual string fields have no length cap — the body size is the limit.

Required scope: events:write.

POST /tr/api/events

cURL

purchase

curl --request POST \
  --url https://api.upstackdata.com/tr/api/events \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "events": [
    {
      "name": "purchase",
      "eventId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "identityId": "01HXYZ_BROWSER_ADTIK",
      "userProperties": {
        "emails": [
          "[e-mail]"
        ],
        "userIds": [
          "cust_889"
        ],
        "shopifyYIds": [
          "y-abc"
        ]
      },
      "ipAddress": "203.0.113.5",
      "page": {
        "url": "https://shop.com/checkout"
      },
      "click": {
        "fbc": "fb.1.abc",
        "gclid": "xyz",
        "fbclid": "IwAR…"
      },
      "viewport": {
        "viewportWidth": 1440,
        "viewportHeight": 900,
        "pageHeight": 3200,
        "devicePixelRatio": 2
      },
      "eventProperties": {
        "orderId": "10421",
        "value": 99.9,
        "currency": "USD",
        "items": [
          {
            "id": "SKU1",
            "name": "Tee",
            "price": 49.95,
            "quantity": 2
          }
        ]
      }
    }
  ]
}
'

200

{
  "requestId": "18d90656-34fd-4b87-b1e2-9607943d97a9",
  "eventsIngested": 3
}

Authorizations

x-api-key · string · header · required

Your Upstack API key. Starts with upstack_.

x-pixel-id · string · header · required

The pixel id the request targets.

Body

application/json

events · object[] · required

The events to ingest. At least 1, at most 100 per request.

Required array length: 1 - 100 elements

Show child attributes

Response

200

application/json

Events accepted for processing. eventsIngested is the number queued.

requestId · string · required

Unique id for this request (also the x-request-id header).

eventsIngested · integer · required

Number of events accepted and queued for processing.