API resource

Conversions and tracking links

Server-side conversions with the Ads add-on: send each conversion once and it is forwarded to every ad network you choose, see what was sent and how well it matched, turn on tracking for your website or store, and make tracking links that split-test landing pages and report conversions back to the network. Also store leads from your own forms next to the ones from lead ads.

List stored events

GET/v1/events

Works on: Meta, Google, TikTok, LinkedIn ads

Lists the conversion events stored by POST /v1/events, newest first: for one profile, or for every profile you can access when profileId is omitted. Personal data is never returned: hasEmail, hasPhone and hasExternalId only say whether the event carried that identifier. Events sent with testCode are not stored, so they never appear here. Paginate with cursor: pass the nextCursor of the previous page until it comes back null.

Query parameters

limitinteger

fromstring

Only events at or after this time (ISO 8601, on the event time).

tostring

Only events before this time (ISO 8601, on the event time).

eventNamestring

Only events with this name, such as Purchase.

sourcestring

Only events from this source, such as stripe for the payments of a connected Stripe account. One of: api, relay, hubspot, meta_leads, google_leads, linkedin_leads, tiktok_leads, shopify, woocommerce, stripe, web, salesforce, postback, form_leads.

platformstring

Only events sent to this ad platform, such as metaads or googleads.

deliveryStatusstring

Only events whose latest send to a destination (of platform, when given) was accepted (sent) or was not (failed: failed or still retrying). One of: sent, failed.

fromAdboolean

true: only events carrying an ad click or a campaign (a gclid, gbraid or wbraid, a zrn, or a matched campaign). false: only the others.

campaignIdstring

Only events of this ad platform campaign id: matched to it, or behind a Google click of it.

cursorstring

nextCursor from the previous page.

curl "https://creatoros-production-5658.up.railway.app/v1/events" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "events": [
    {
      "eventId": "obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9",
      "source": "string",
      "eventName": "string",
      "eventTime": "2026-10-10T00:00:00.000Z",
      "receivedAt": "2026-10-10T00:00:00.000Z",
      "actionSource": "string",
      "value": 0,
      "currency": "string",
      "sourceUrl": "string",
      "utm": {
        "source": "string",
        "medium": "string",
        "campaign": "string",
        "content": "string"
      },
      "zrn": "string",
      "clickIds": {
        "gclid": "string",
        "fbc": "string"
      },
      "destinationsSent": 0,
      "hasEmail": true,
      "hasPhone": true,
      "hasExternalId": true,
      "pairedEventId": "string",
      "ad": {
        "platform": "social",
        "customerId": "string",
        "campaignId": "string",
        "adGroupId": "string",
        "adSetId": "string",
        "adId": "string"
      },
      "campaign": {
        "via": "google_click",
        "id": "string",
        "name": "string",
        "adGroupName": "string",
        "adName": "string"
      },
      "counted": true,
      "deliveries": [
        {}
      ]
    }
  ],
  "nextCursor": "string"
}

Send events to every destination

POST/v1/events

Works on: Meta, Google, TikTok, LinkedIn ads

The recommended way to send conversions. Sends conversion events once and forwards them to every ad platform destination saved for the profile (see POST /v1/events/destinations), or to the destinations given in the request. Requires the Ads add-on. ### Forwarding - Each destination receives the events exactly as POST /v1/ads/conversions would send them, so the per-platform notes there (hashing, batching, eventName semantics, dedup on eventId) apply here too. - A destination saved with eventNames only receives events with those names.

Body

eventsobject[]required

destinationsobject[]

Send to these destinations instead of the saved ones (every event goes to each).

consentobject

Batch-level user consent, forwarded to every destination (see POST /v1/ads/conversions).

testCodestring

Forwarded as each platform test code (see POST /v1/ads/conversions). A root-level test_event_code is accepted as an alias. Test events are not stored.

modestring

sync sends to every destination before answering (200, per-destination results). async stores and queues the sends, then answers 202 at once; each send is retried while the platform fails for now, and its outcome shows on GET /v1/events/{eventId}. Requests with testCode always send now.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/events" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "eventName": "Purchase",
        "eventTime": 1744732800,
        "eventId": "order_abc_123",
        "value": 99.5,
        "currency": "USD",
        "user": {
          "email": "string",
          "phone": "string",
          "firstName": "string",
          "lastName": "string",
          "externalId": "string",
          "ipAddress": "string",
          "userAgent": "string",
          "country": "string",
          "city": "string",
          "state": "string",
          "zip": "string",
          "dob": "string",
          "gender": "string",
          "leadId": "string",
          "visitorId": "4f9c2e1a-7b3d-4c8e-9a1f-2d6b5e8c0a73",
          "clickIds": {
            "fbc": "string",
            "fbp": "string",
            "gclid": "string",
            "gbraid": "string",
            "wbraid": "string",
            "li_fat_id": "string",
            "epik": "string",
            "rdt_cid": "string",
            "rdt_uuid": "string",
            "aleid": "string",
            "alart": "string",
            "axwrt": "string",
            "twclid": "string",
            "msclkid": "string",
            "sccid": "string",
            "scid": "string"
          }
        },
        "items": [
          {
            "id": "string",
            "name": "string",
            "price": 0,
            "quantity": 0,
            "category": "string"
          }
        ],
        "sourceUrl": "string",
        "campaign": {
          "id": "string",
          "name": "string"
        },
        "actionSource": "web",
        "messaging": {
          "channel": "whatsapp",
          "wabaId": "string",
          "ctwaClid": "string",
          "pageId": "112233445566",
          "instagramBusinessAccountId": "string",
          "pageScopedUserId": "string",
          "instagramScopedUserId": "string"
        },
        "platformData": {}
      }
    ]
  }'
Response 200
{
  "eventsReceived": 0,
  "stored": true,
  "testCode": "string",
  "destinations": [
    {
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "platform": "social",
      "eventsSent": 0,
      "eventsFailed": 0,
      "failures": [
        {}
      ],
      "error": "string",
      "retrying": true,
      "traceId": "string",
      "platformMessages": [
        "string"
      ]
    }
  ],
  "queuedDestinations": 0
}

List the touch paths that lead to conversions

GET/v1/events/paths

Works on: Meta, Google, TikTok, LinkedIn ads

The most frequent sequences of touches people made before a conversion (sale, lead or another counted event) whose time falls in the range: ad clicks, tagged visits, search, referrals and earlier lead forms, oldest first. Only conversions with more than one touch have a path. Without profileId it covers every profile you can access. Requires the Ads add-on.

Query parameters

fromDatestringrequired

toDatestringrequired

Inclusive. At most 400 days after fromDate.

limitinteger

curl "https://creatoros-production-5658.up.railway.app/v1/events/paths?fromDate=%3CfromDate%3E&toDate=%3CtoDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "fromDate": "2026-10-10T00:00:00.000Z",
  "toDate": "2026-10-10T00:00:00.000Z",
  "paths": [
    {
      "steps": [
        "string"
      ],
      "conversions": 0,
      "sales": 0,
      "revenue": 0,
      "avgDays": 0
    }
  ]
}

Get post-purchase survey answers

GET/v1/events/survey

Works on: Meta, Google, TikTok, LinkedIn ads

How buyers said they heard about the store, from the "How did you hear about us?" block on the Shopify thank-you page. Each answer comes with its orders and their revenue. Revenue is what the orders are worth now (refunds taken off), summed across currencies as sent. Without profileId it covers every profile you can access. Requires the Ads add-on.

Query parameters

fromDatestringrequired

First day an answer was given.

toDatestringrequired

Inclusive. At most 400 days after fromDate.

curl "https://creatoros-production-5658.up.railway.app/v1/events/survey?fromDate=%3CfromDate%3E&toDate=%3CtoDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "fromDate": "2026-10-10T00:00:00.000Z",
  "toDate": "2026-10-10T00:00:00.000Z",
  "answers": [
    {
      "answer": "Podcast",
      "orders": 0,
      "revenue": 0
    }
  ]
}

Get buyer cohorts by first purchase month and first channel

GET/v1/events/ltv

Works on: Meta, Google, TikTok, LinkedIn ads

Buyers grouped by the month of their first purchase and the platform that first brought them, with their purchases added up over the year after (months 0, 1, 3, 6 and 12). A buyer is a hashed email, else external id, else phone. The first channel is the first touch's platform, else the first purchase's own campaign, else none. Values stay in each purchase's currency, one row per currency. Requires the Ads add-on.

Query parameters

fromMonthstringrequired

toMonthstringrequired

curl "https://creatoros-production-5658.up.railway.app/v1/events/ltv?fromMonth=%3CfromMonth%3E&toMonth=%3CtoMonth%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "fromMonth": "string",
  "toMonth": "string",
  "cohorts": [
    {
      "cohort": "2026-09",
      "channel": "facebook",
      "currency": "string",
      "customers": 0,
      "revenue": {
        "m0": 0,
        "m1": 0,
        "m3": 0,
        "m6": 0,
        "m12": 0
      }
    }
  ]
}

Get delivery accuracy per destination

GET/v1/events/accuracy

Works on: Meta, Google, TikTok, LinkedIn ads

For each forwarding rule of a profile: what its destination received over a period, and how many of the profile's real sales reached it. deliveries counts every event sent to the destination in the period, whatever its source, by the latest outcome of each. accuracy compares only sales: Shopify and WooCommerce orders and Stripe payments, as Elevar's Channel Accuracy does. Sales a rule leaves out by choice do not count against it. Without profileId it covers every profile you can access. Requires the Ads add-on.

Query parameters

periodstring

The window, ending now: today (since 00:00 UTC), or the last 7, 30 or 90 days. One of: today, 7d, 30d, 90d.

curl "https://creatoros-production-5658.up.railway.app/v1/events/accuracy" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "period": "today",
  "destinations": [
    {
      "ruleId": "obj_Ru4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platform": "social",
      "accountName": "string",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "sales": 0,
      "sent": 0,
      "accepted": 0,
      "failed": 0,
      "retrying": 0,
      "notSent": 0,
      "accuracy": 0,
      "deliveries": {
        "events": 0,
        "accepted": 0,
        "failed": 0,
        "retrying": 0
      },
      "match": {
        "events": 0,
        "identified": 0,
        "email": 0,
        "phone": 0,
        "externalId": 0,
        "clickId": 0
      },
      "matchRate": 0
    }
  ]
}

Get today's tracking overview

GET/v1/events/overview

Works on: Meta, Google, TikTok, LinkedIn ads

How a profile's conversion tracking is doing today (UTC day): events stored, how many reached the ad platforms, each forwarding rule's destination, each event source and, when the profile has a tracking site, the site's funnel. Without profileId it covers every profile you can access, summed across them. Requires the Ads add-on.
curl "https://creatoros-production-5658.up.railway.app/v1/events/overview" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "today": {
    "conversions": 0,
    "value": 0,
    "currency": "string",
    "sent": 0,
    "accepted": 0,
    "matched": 0,
    "counted": 0
  },
  "platforms": [
    {
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platform": "social",
      "accountName": "string",
      "destinationName": "string",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "sentToday": 0,
      "failedToday": 0,
      "lastSentAt": "2026-10-10T00:00:00.000Z",
      "lastEventName": "string",
      "lastError": "string",
      "fixUrl": "string"
    }
  ],
  "sources": [
    {
      "source": "string",
      "label": "string",
      "state": "on",
      "eventsToday": 0,
      "lastSeenAt": "2026-10-10T00:00:00.000Z"
    }
  ],
  "website": {
    "steps": [
      {
        "name": "string",
        "label": "string",
        "count": 0
      }
    ],
    "recovered": 0,
    "conversions": 0,
    "consented": 0,
    "visits": 0,
    "bots": 0,
    "serverPlatforms": [
      "string"
    ]
  },
  "sites": [
    {
      "siteId": "obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq",
      "hitsToday": 0,
      "lastActiveOn": "string",
      "totals": {
        "today": {},
        "7d": {},
        "30d": {}
      }
    }
  ],
  "eventNames": [
    {
      "eventName": "string",
      "serverSources": [
        "string"
      ],
      "fromWebsite": true,
      "websiteToday": 0,
      "serverToday": 0
    }
  ]
}

Get daily tracking figures

GET/v1/events/overview/daily

Works on: Meta, Google, TikTok, LinkedIn ads

The tracking figures of a period, day by day (UTC): events stored per event name, events sent to each ad platform and how many it accepted, the period's totals in the same shape as the overview's today, and how many website conversions each platform's browser pixel missed. An event sent to a destination counts once, on the day of its first send, by its latest outcome. Without profileId it covers every profile you can access. eventName, sources and platform narrow every figure. Requires the Ads add-on.

Query parameters

periodstring

The days to cover, each ending today (UTC): today, the last 7, 30 or 90 days. One of: today, 7d, 30d, 90d.

eventNamestring

Only events of this name, such as Purchase.

sourcesstring

Comma-separated sources (web, shopify, stripe, api...). Only events from them.

platformstring

Only sends to this platform (metaads, googleads...), and only the events sent to it.

curl "https://creatoros-production-5658.up.railway.app/v1/events/overview/daily" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "period": "today",
  "totals": {
    "conversions": 0,
    "value": 0,
    "valueSent": 0,
    "currency": "string",
    "sent": 0,
    "accepted": 0,
    "matched": 0,
    "counted": 0,
    "fromAds": 0
  },
  "days": [
    {
      "day": "string",
      "conversions": 0,
      "sent": 0,
      "accepted": 0,
      "value": 0,
      "valueSent": 0,
      "fromAds": 0,
      "matched": 0,
      "byEvent": {}
    }
  ],
  "eventNames": [
    "string"
  ],
  "platforms": [
    {
      "platform": "social",
      "sent": 0,
      "accepted": 0,
      "days": [
        {}
      ]
    }
  ],
  "pixelMissed": [
    {
      "platform": "social",
      "conversions": 0,
      "missed": 0,
      "days": [
        {}
      ]
    }
  ],
  "breakdown": {
    "events": [
      {
        "eventName": "string",
        "conversions": 0
      }
    ],
    "sources": [
      {
        "source": "string",
        "conversions": 0
      }
    ],
    "campaigns": [
      {
        "platform": "social",
        "campaignId": "string",
        "name": "string",
        "reason": "not_from_an_ad",
        "conversions": 0,
        "value": 0
      }
    ]
  },
  "previous": {
    "totals": {},
    "days": [
      {}
    ],
    "pixelMissed": [
      {}
    ]
  }
}

List stored event names

GET/v1/events/names

Works on: Meta, Google, TikTok, LinkedIn ads

The event names stored for a profile in the last 30 days, with how many events carry each, most used first. It includes custom names, such as a site's own events, so you can filter GET /v1/events by eventName. Without profileId it covers every profile you can access. Retracted events are left out. Requires the Ads add-on.
curl "https://creatoros-production-5658.up.railway.app/v1/events/names" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "names": [
    {
      "name": "string",
      "events": 0
    }
  ]
}

List event destinations

GET/v1/events/destinations

Works on: Meta, Google, TikTok, LinkedIn ads

The first name of GET /v1/events/forwarding-rules, which lists the same rules. It keeps working and answers under destinations.
curl "https://creatoros-production-5658.up.railway.app/v1/events/destinations" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "destinations": [
    {
      "id": "string",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "eventNames": [
        "string"
      ],
      "createdAt": "2026-10-10T00:00:00.000Z"
    }
  ]
}

Add an event destination

POST/v1/events/destinations

Works on: Meta, Google, TikTok, LinkedIn ads

The first name of POST /v1/events/forwarding-rules, which saves the same rule. It keeps working and answers under destination.

Body

accountIdstringrequired

Connected ads account ID that owns the destination.

destinationIdstringrequired

eventNamesstring[]

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/events/destinations" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1"
  }'
Response 200
{
  "destination": {
    "id": "string",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
    "eventNames": [
      "string"
    ],
    "createdAt": "2026-10-10T00:00:00.000Z"
  }
}

Remove an event destination

DELETE/v1/events/destinations/{destinationId}

Works on: Meta, Google, TikTok, LinkedIn ads

The first name of DELETE /v1/events/forwarding-rules/{ruleId}. destinationId here is the rule id, not the platform destination.

Path parameters

destinationIdstringrequired

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/events/destinations/obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "deleted": true
}

List forwarding rules

GET/v1/events/forwarding-rules

Works on: Meta, Google, TikTok, LinkedIn ads

Lists the forwarding rules of one profile, or of every profile you can access. A rule sends a profile's events to one ad platform destination.
curl "https://creatoros-production-5658.up.railway.app/v1/events/forwarding-rules" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "forwardingRules": [
    {
      "id": "string",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "eventNames": [
        "string"
      ],
      "sources": [
        "api"
      ],
      "apiSecretVerified": true,
      "createdAt": "2026-10-10T00:00:00.000Z"
    }
  ]
}

Add a forwarding rule

POST/v1/events/forwarding-rules

Works on: Meta, Google, TikTok, LinkedIn ads

Saves where a profile's events go: every event sent to POST /v1/events for that profile is then forwarded to this destination. Pick destinationId from GET /v1/ads/conversions/destinations. Set eventNames to forward only those events, such as only Purchase; leave it out to forward every event.

Body

accountIdstringrequired

Connected ads account ID that owns the destination.

destinationIdstringrequired

The platform destination: a pixel, a conversion action, a conversion rule, or a GA4 web stream measurement id (G-…).

eventNamesstring[]

sourcesstring[]

Forward only events from these sources, such as only web for a tracked website. Leave it out to forward events from every source.

apiSecretstring

Google Analytics streams only: the stream's Measurement Protocol API secret (GA4 Admin › Data streams). Optional when the connection has edit access, since Creator OS then creates it. Checked against Google's validation server, stored encrypted, never returned. Change it with PATCH /v1/events/forwarding-rules/{ruleId}.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/events/forwarding-rules" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1"
  }'
Response 200
{
  "forwardingRule": {
    "id": "string",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
    "eventNames": [
      "string"
    ],
    "sources": [
      "api"
    ],
    "apiSecretVerified": true,
    "createdAt": "2026-10-10T00:00:00.000Z"
  }
}

Change a forwarding rule's API secret

PATCH/v1/events/forwarding-rules/{ruleId}

Works on: Meta, Google, TikTok, LinkedIn ads

Replaces the apiSecret of a rule whose destination needs one, such as a Google Analytics data stream's Measurement Protocol API secret. Before saving, Creator OS sends one hit to Google's validation server; Google does not confirm the secret itself, so check GA4 Realtime after the next events.

Path parameters

ruleIdstringrequired

The rule id.

Body

apiSecretstringrequired

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/events/forwarding-rules/obj_Ru4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiSecret": "string"
  }'
Response 200
{
  "forwardingRule": {
    "id": "string",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
    "eventNames": [
      "string"
    ],
    "sources": [
      "api"
    ],
    "apiSecretVerified": true,
    "createdAt": "2026-10-10T00:00:00.000Z"
  }
}

Remove a forwarding rule

DELETE/v1/events/forwarding-rules/{ruleId}

Works on: Meta, Google, TikTok, LinkedIn ads

Stops forwarding events to this rule's destination. Events already sent are not affected.

Path parameters

ruleIdstringrequired

The rule id.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/events/forwarding-rules/obj_Ru4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "deleted": true
}

Get one stored event and its deliveries

GET/v1/events/{eventId}

Works on: Meta, Google, TikTok, LinkedIn ads

Returns one stored event of a profile (the latest copy of it) and, for each destination it was forwarded to, the newest send: sent, retrying (failed for now and queued again) or failed (final). Requires the Ads add-on.

Path parameters

eventIdstringrequired

The eventId the event was sent with.

curl "https://creatoros-production-5658.up.railway.app/v1/events/obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "event": {
    "eventId": "obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9",
    "source": "string",
    "eventName": "string",
    "eventTime": "2026-10-10T00:00:00.000Z",
    "receivedAt": "2026-10-10T00:00:00.000Z",
    "actionSource": "string",
    "value": 0,
    "currency": "string",
    "sourceUrl": "string",
    "utm": {
      "source": "string",
      "medium": "string",
      "campaign": "string",
      "content": "string"
    },
    "zrn": "string",
    "clickIds": {
      "gclid": "string",
      "fbc": "string"
    },
    "destinationsSent": 0,
    "hasEmail": true,
    "hasPhone": true,
    "hasExternalId": true,
    "pairedEventId": "string",
    "ad": {
      "platform": "social",
      "customerId": "string",
      "campaignId": "string",
      "adGroupId": "string",
      "adSetId": "string",
      "adId": "string"
    },
    "campaign": {
      "via": "google_click",
      "id": "string",
      "name": "string",
      "adGroupName": "string",
      "adName": "string"
    },
    "counted": true
  },
  "deliveries": [
    {
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "platform": "social",
      "status": "sent",
      "attempt": 0,
      "error": "string",
      "errorCode": "string",
      "sentAt": "2026-10-10T00:00:00.000Z"
    }
  ],
  "touches": [
    {
      "at": "2026-10-10T00:00:00.000Z",
      "kind": "ad_click",
      "platform": "social",
      "adAccountId": "string",
      "campaignId": "string",
      "campaignName": "string",
      "detail": {
        "referrer": "string",
        "page": "string",
        "utmSource": "string",
        "utmMedium": "string",
        "utmCampaign": "string",
        "eventName": "string",
        "answer": "string"
      },
      "credit": {}
    }
  ],
  "after": [
    {
      "eventId": "obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9",
      "eventName": "string",
      "source": "string",
      "eventTime": "2026-10-10T00:00:00.000Z",
      "value": 0,
      "currency": "string"
    }
  ]
}

Change a stored event's value

PATCH/v1/events/{eventId}

Works on: Meta, Google, TikTok, LinkedIn ads

Changes the value of an event you already sent, for a partial refund or an upgrade. Send the corrected total, not a difference. Creator OS stores a new version of the event, so campaign results count the new value at once. It then passes the change to each destination the event reached: Google Ads restates the conversion, and platforms without a correction API report not_supported and keep their count.

Path parameters

eventIdstringrequired

The eventId the event was sent with.

Body

valuenumberrequired

The corrected total value.

currencystring

ISO 4217 code such as USD. Defaults to the currency the event was sent with.

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/events/obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 0
  }'
Response 200
{
  "eventId": "obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9",
  "value": 0,
  "destinations": [
    {
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "platform": "social",
      "status": "corrected",
      "error": "string"
    }
  ]
}

Retract a stored event

DELETE/v1/events/{eventId}

Works on: Meta, Google, TikTok, LinkedIn ads

Retracts an event you already sent, for a refund, a cancelled order or a lost deal. It stops counting in campaign results and ad rules. Each destination the event reached is told where the platform allows it: Google Ads retracts the conversion, and the other platforms report not_supported and keep their count. Sending the same eventId again stores it anew.

Path parameters

eventIdstringrequired

The eventId the event was sent with.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/events/obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "eventId": "obj_Ev2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9",
  "deleted": true,
  "destinations": [
    {
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "destinationId": "obj_Ds8Kq3Vw6Nx1Ty9Lm4Rc7Hb2Js5Df0Ga3Ue8Ki6Oq1",
      "platform": "social",
      "status": "corrected",
      "error": "string"
    }
  ]
}

List tracking sites

GET/v1/tracking-sites

Works on: Meta, Google, TikTok, LinkedIn ads

The websites whose visits and conversions Creator OS collects, newest first. Pass profileId to list one profile's sites.

Query parameters

limitinteger

cursorstring

pagination.nextCursor from the previous page.

curl "https://creatoros-production-5658.up.railway.app/v1/tracking-sites" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "sites": [
    {
      "id": "string",
      "name": "string",
      "status": "active",
      "install": {
        "method": "shopify",
        "storeAccountId": "string",
        "snippet": "string"
      },
      "storeOrders": true,
      "siteKey": "string",
      "domains": [
        "string"
      ],
      "customHostname": {
        "hostname": "string",
        "status": "pending",
        "dnsRecord": {}
      },
      "proxy": {
        "path": "string",
        "secret": "string",
        "googleTags": []
      },
      "googleTagIds": [
        "string"
      ],
      "consentMode": "eu_opt_in",
      "checks": [
        {}
      ],
      "setup": {
        "status": "pending"
      },
      "createdAt": "2026-10-10T00:00:00.000Z",
      "updatedAt": "2026-10-10T00:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "string"
  }
}

Turn on server-side tracking for a website

POST/v1/tracking-sites

Works on: Meta, Google, TikTok, LinkedIn ads

Creates a tracking site. With storeAccountId, Creator OS installs its tag on the connected Shopify, WordPress (WooCommerce), Wix or Webflow store. With only url, paste the returned install.snippet into the site. The ad accounts you picked for each connection get a forwarding rule, so website conversions reach them at once. checks shows each step; setup.status turns ready when all have passed.

Body

storeAccountIdstringrequired

A Shopify, WordPress, Wix or Webflow account connected to the profile.

urlstring

The store's public address, when it differs from the one the store reports.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/tracking-sites" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storeAccountId": "string"
  }'
Response 200
{
  "site": {
    "id": "string",
    "name": "string",
    "status": "active",
    "install": {
      "method": "shopify",
      "storeAccountId": "string",
      "snippet": "string"
    },
    "storeOrders": true,
    "siteKey": "string",
    "domains": [
      "string"
    ],
    "customHostname": {
      "hostname": "string",
      "status": "pending",
      "dnsRecord": {
        "type": "CNAME",
        "name": "string",
        "target": "string"
      }
    },
    "proxy": {
      "path": "string",
      "secret": "string",
      "googleTags": [
        {}
      ]
    },
    "googleTagIds": [
      "string"
    ],
    "consentMode": "eu_opt_in",
    "checks": [
      {
        "key": "string",
        "status": "pending",
        "detail": "string",
        "checkedAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "setup": {
      "status": "pending"
    },
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z"
  }
}

Get a tracking site

GET/v1/tracking-sites/{siteId}

Works on: Meta, Google, TikTok, LinkedIn ads

One site, with its snippet, its custom subdomain and the latest result of each setup check.
curl "https://creatoros-production-5658.up.railway.app/v1/tracking-sites/obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "site": {
    "id": "string",
    "name": "string",
    "status": "active",
    "install": {
      "method": "shopify",
      "storeAccountId": "string",
      "snippet": "string"
    },
    "storeOrders": true,
    "siteKey": "string",
    "domains": [
      "string"
    ],
    "customHostname": {
      "hostname": "string",
      "status": "pending",
      "dnsRecord": {
        "type": "CNAME",
        "name": "string",
        "target": "string"
      }
    },
    "proxy": {
      "path": "string",
      "secret": "string",
      "googleTags": [
        {}
      ]
    },
    "googleTagIds": [
      "string"
    ],
    "consentMode": "eu_opt_in",
    "checks": [
      {
        "key": "string",
        "status": "pending",
        "detail": "string",
        "checkedAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "setup": {
      "status": "pending"
    },
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z"
  }
}

Update a tracking site

PATCH/v1/tracking-sites/{siteId}

Works on: Meta, Google, TikTok, LinkedIn ads

Changes the site's name, domains, consent mode, custom subdomain or own-domain path. Send at least one field. customHostname sets a subdomain of the site, such as t.brand.com; create the CNAME in customHostname.dnsRecord. The snippet switches to it once its status is active. null removes it. proxyPath serves the tag from a path of the site itself, such as brand.com/zt, through a proxy on your server. The response's proxy.secret signs what the proxy forwards. null removes it. googleTagIds lists the site's own Google tags that the same proxy relays to Google's tag gateway.

Body

namestring

domainsstring[]

Hosts allowed to send events, such as brand.com. Events from any other origin are dropped.

consentModestring

How a visitor with no consent signal is treated. eu_opt_in (default): no consent in the EU, UK and other countries that require it, consent elsewhere. opt_in: no consent anywhere. opt_out: consent everywhere.

customHostnamestring

A subdomain of one of the site's domains, never the domain itself. null removes it.

proxyPathstring

The path your server forwards to the collector, such as /zt. null removes it.

googleTagIdsstring[]

Google tag ids such as GTM-XXXXXXX, G-XXXXXXXXXX or AW-XXXXXXXXXX, up to 10. null or [] removes them.

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/tracking-sites/obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'
Response 200
{
  "site": {
    "id": "string",
    "name": "string",
    "status": "active",
    "install": {
      "method": "shopify",
      "storeAccountId": "string",
      "snippet": "string"
    },
    "storeOrders": true,
    "siteKey": "string",
    "domains": [
      "string"
    ],
    "customHostname": {
      "hostname": "string",
      "status": "pending",
      "dnsRecord": {
        "type": "CNAME",
        "name": "string",
        "target": "string"
      }
    },
    "proxy": {
      "path": "string",
      "secret": "string",
      "googleTags": [
        {}
      ]
    },
    "googleTagIds": [
      "string"
    ],
    "consentMode": "eu_opt_in",
    "checks": [
      {
        "key": "string",
        "status": "pending",
        "detail": "string",
        "checkedAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "setup": {
      "status": "pending"
    },
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z"
  }
}

Delete a tracking site

DELETE/v1/tracking-sites/{siteId}

Works on: Meta, Google, TikTok, LinkedIn ads

Stops collecting at once, removes the tag from the connected store and releases the custom subdomain. Events already stored are kept.
curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/tracking-sites/obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "ok": true
}

Rotate a tracking site's key

POST/v1/tracking-sites/{siteId}/rotate-key

Works on: Meta, Google, TikTok, LinkedIn ads

Issues a new siteKey. The old key keeps working for 7 days, so update the snippet on your site within that time.

Path parameters

siteIdstringrequired

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/tracking-sites/obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq/rotate-key" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "site": {
    "id": "string",
    "name": "string",
    "status": "active",
    "install": {
      "method": "shopify",
      "storeAccountId": "string",
      "snippet": "string"
    },
    "storeOrders": true,
    "siteKey": "string",
    "domains": [
      "string"
    ],
    "customHostname": {
      "hostname": "string",
      "status": "pending",
      "dnsRecord": {
        "type": "CNAME",
        "name": "string",
        "target": "string"
      }
    },
    "proxy": {
      "path": "string",
      "secret": "string",
      "googleTags": [
        {}
      ]
    },
    "googleTagIds": [
      "string"
    ],
    "consentMode": "eu_opt_in",
    "checks": [
      {
        "key": "string",
        "status": "pending",
        "detail": "string",
        "checkedAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "setup": {
      "status": "pending"
    },
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z"
  }
}

Create a tracking link

POST/v1/tracking-links

Works on: Meta, Google, TikTok, LinkedIn ads

Creates a short link on a tracking site. Each click goes to one of destinations, picked by weight, so the link also split-tests landing pages. Put url in your ads and give postbackUrl to the network that reports conversions server to server.

Body

siteIdstringrequired

The tracking site the link belongs to. The link takes its profile.

namestringrequired

destinationsobject[]required

campaignobject

Hints that conversions from this link use to match a campaign. Every field is optional.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/tracking-links" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq",
    "name": "string",
    "destinations": [
      {
        "url": "string",
        "weight": 0
      }
    ]
  }'
Response 200
{
  "link": {
    "id": "string",
    "name": "string",
    "code": "string",
    "siteId": "obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq",
    "status": "active",
    "destinations": [
      {
        "url": "string",
        "weight": 0
      }
    ],
    "campaign": {
      "platform": "social",
      "campaignId": "string",
      "utmCampaign": "string"
    },
    "url": "string",
    "postbackUrl": "string",
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z"
  }
}

Rotate a tracking link's postback URL

POST/v1/tracking-links/{linkId}/rotate-postback-token

Works on: Meta, Google, TikTok, LinkedIn ads

Issues a new postbackUrl. The old one stops working at once, so update it at the network right after.

Path parameters

linkIdstringrequired

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/tracking-links/obj_Lk6Tn2Vw9Kx4Ry1Lm8Qc5Hb3Js7Df0Ga2Ue6Ki9Oq/rotate-postback-token" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "link": {
    "id": "string",
    "name": "string",
    "code": "string",
    "siteId": "obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq",
    "status": "active",
    "destinations": [
      {
        "url": "string",
        "weight": 0
      }
    ],
    "campaign": {
      "platform": "social",
      "campaignId": "string",
      "utmCampaign": "string"
    },
    "url": "string",
    "postbackUrl": "string",
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z"
  }
}

Create a lead from your own form

POST/v1/leads

Works on: Meta, Google, TikTok, LinkedIn ads

Stores a lead from a form on your own site or app, posted by your backend. It joins the leads from ad networks: it is listed on GET /v1/ads/leads (platform: web), fires lead.received, starts lead workflows, and moves through statuses with PATCH /v1/ads/leads/{id}. - Lead event. A Lead event is stored and sent through the profile's forwarding rules that take the form_leads source, like an event sent to POST /v1/events. - Attribution. Pass the ad click ids from the landing URL in clickIds (a raw fbclid becomes Meta's fbc) and the Creator OS tag's visitor id (_zid cookie) in visitorId.

Body

emailstring

Required unless phone is given.

phonestring

Required unless email is given. E.164 is best.

fieldsobject

Other answers, field name to value (full_name, company, ...). Stored on the lead, never sent to an ad platform.

formIdstring

Your id for the form. Defaults to api.

formNamestring

leadIdstring

Your id for this lead (a CRM id, a submission id). Makes the call idempotent.

submittedAtstring

When the form was submitted. Defaults to now.

sourceUrlstring

The page the form was submitted on, with its query string.

visitorIdstring

The Creator OS tag visitor id, from the _zid cookie.

clickIdsobject

Ad click and browser ids: fbclid or fbc, fbp, gclid, gbraid, wbraid, ttclid, msclkid, li_fat_id, ...

utmobject

utm_source, utm_campaign, ...

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/leads" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "string"
  }'
Response 200
{
  "lead": {
    "id": "string",
    "platform": "social",
    "leadgenId": "string",
    "formId": "string",
    "formName": "string",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "adId": "string",
    "adsetId": "string",
    "campaignId": "string",
    "isOrganic": true,
    "createdTime": "2026-10-10T00:00:00.000Z",
    "fields": {},
    "fieldData": [
      {}
    ],
    "consents": [
      {
        "checkboxKey": "string",
        "isChecked": true
      }
    ],
    "contentNotRetained": true,
    "status": "new",
    "statusChangedAt": "2026-10-10T00:00:00.000Z",
    "value": 0,
    "currency": "string",
    "contactId": "obj_Ct9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq4C",
    "firstContactedAt": "2026-10-10T00:00:00.000Z",
    "conversationId": "conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6",
    "webhookDeliveredAt": "2026-10-10T00:00:00.000Z",
    "attribution": {
      "clickIds": {},
      "utm": {},
      "visitorId": "string",
      "sourceUrl": "string",
      "siteId": "obj_St9Wm3Kq1Vz6Ny4Lb8Hc2Jr5Pd0Fs7Ga3Ue9Ki1Oq"
    }
  },
  "created": true
}