Conversion Events

Post a conversion another system saw

Records a fact the site cannot see itself — a reservation paid on a booking site, a lead that became a customer — as an event with source: external, and delivers it to the ad platforms the Conversion reports to (Google Ads, Google Analytics 4, Meta, TikTok server APIs). Google Analytics only accepts it within 72 hours of when it happened.

Joining. The CMS joins the fact to a visitor’s journey with match, strongest first (visitor ID, the fk_at token, _gcl_au, a click ID, hashed email / phone), and copies that visitor’s attribution onto the event. join.by in the answer says which matched. The producer’s own click IDs win over the visitor record’s; its browser IDs only fill gaps.

Consent. The producer’s consent flags govern what is sent about the fact (omitted flags are granted). A denial trims what is sent — no contact details or browser data, Google receives CONSENT_DENIED — but the conversion is always stored and delivered.

Browser context. Send the customer’s client (IP, user agent) and page.url as captured when they booked; with them the fact reaches Meta as a website event (de-duplicated against the pixel), without them as system_generated.

Idempotent on eventId. Posting the same fact again returns the stored event with created: false; the same ID with different content is a 409. Retry freely.

Access: an API key with conversions:write — or its group master ads:all, or admin:all — or a signed-in user holding the conversion-events:write permission. Anonymous callers get 404.

Signed: every API key must sign this request (X-Fetchski-Timestamp + X-Fetchski-Signature, see the headers below), whatever its own signing mode. Signed-in users in the CMS need no signature. Signing requests shows how, from the API and both SDKs.

Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120); over it, 429 with Retry-After.

POST

conversion-event

external

cURL

curl --request POST \
  --url https://{host}/api/v1/conversion-event/external \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventId": "tenant-42:order:1234:purchase",
  "conversion": "purchase",
  "producer": {
    "system": "reservation",
    "ref": "booking-1234"
  }
}
'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const createExternalConversionEvent = await site.conversionEvents().createExternalConversionEvent({ eventId: 'tenant-42:order:1234:purchase', conversion: 'booking', producer: { system: 'reservation' } });

use Fetchski\AttractCmsLaravel\Facades\Attract;

$createExternalConversionEvent = Attract::conversionEvents()->createExternalConversionEvent(eventId: 'tenant-42:order:1234:purchase', conversion: 'booking', producer: ['system' => 'reservation']);

{
  "created": true,
  "event": {
    "eventId": "tenant-42:orders:1234:purchase",
    "conversion": {
      "id": "ckq1w2e3r4t5y6u7i8o9p0",
      "key": "booking",
      "title": "Booking"
    },
    "trigger": {
      "type": "external",
      "ref": "booking-1234"
    },
    "source": "external",
    "occurredAt": "2026-09-21T15:04:05.000Z",
    "recordedAt": "2026-09-21T15:04:05.412Z",
    "updatedAt": "2026-09-21T15:04:07.020Z",
    "page": {
      "url": "https://example.com/contact?gclid=Cj0KCQjw",
      "path": "/contact",
      "referrer": "https://www.google.com"
    },
    "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
    "attribution": {
      "firstTouch": {
        "at": "2026-09-20T09:12:00.000Z",
        "path": "/",
        "landingUrl": "https://example.com/?gclid=Cj0KCQjw",
        "referrerOrigin": "https://www.google.com",
        "adPlatforms": [
          "google"
        ],
        "campaign": {
          "utm_source": "google",
          "utm_campaign": "spring-sale"
        },
        "clickIds": {
          "gclid": "Cj0KCQjw"
        }
      },
      "adPlatforms": [
        "google"
      ],
      "campaign": {
        "utm_source": "google",
        "utm_campaign": "spring-sale"
      },
      "clickIds": {
        "gclid": "Cj0KCQjw"
      },
      "browserIds": {
        "_gcl_au": "1.1.1234567890.1790000000"
      },
      "provenance": {
        "gclid": "ourRecord",
        "_gcl_au": "platformCookie"
      }
    },
    "consent": {
      "categories": {
        "analytics": true,
        "marketing": true
      },
      "mode": "lenient",
      "country": "US",
      "gpc": false,
      "policyVersion": 7
    },
    "value": 3200,
    "currency": "USD",
    "userData": {
      "emailSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneDigitsSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
    },
    "submissionId": "ck9submission1",
    "delivery": {
      "google-ads": {
        "browser": "sent",
        "server": {
          "status": "sent",
          "attempts": 1,
          "sentAt": "2026-09-21T15:04:07.001Z",
          "lastAttemptAt": "2026-09-21T15:04:07.001Z"
        }
      },
      "ga4": {
        "browser": "sent",
        "server": {
          "status": "n/a",
          "attempts": 0
        }
      }
    },
    "status": "active",
    "adjustments": [],
    "producer": {
      "system": "reservation",
      "ref": "booking-1234"
    },
    "join": {
      "by": "token"
    }
  }
}

{
  "name": "invalid",
  "message": "The query is not valid.",
  "data": {
    "errors": [
      {
        "name": "invalid",
        "code": 400,
        "path": "limit",
        "message": "A whole number from 1 to 500.",
        "data": {}
      }
    ]
  }
}

{
  "name": "unauthorized",
  "message": "X-Fetchski-Signature does not match this request.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: conversions:read.",
  "data": {}
}

{
  "name": "notfound",
  "message": "No event with this ID.",
  "data": {}
}

{
  "name": "conflict",
  "message": "An event with this ID is already stored with different content.",
  "data": {
    "eventId": "tenant-42:order:1234:purchase"
  }
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": {
    "retryAfter": 12
  }
}

Authorizations

Authorization

string

header

required

Paste your API key as the CMS showed it: fsk_<site>_<key id>_<secret> (issued under API Keys). ApiKey in front of it works too. Leave it empty to read as the public.

Scopes

conversions:write

Headers

X-Fetchski-Timestamp

string

Required for API keys. The Unix time in seconds when the request was signed; it must be within 5 minutes of the server clock.

Pattern: ^[0-9]{9,11}$

X-Fetchski-Signature

string

Required for API keys. v1= + the lower-case hex HMAC-SHA256, keyed with the API key’s signing secret (fss_…, shown once when the key is created or rotated), of <timestamp>.<METHOD>.<path including query>.<raw request body> — e.g. 1790000000.POST./api/v1/conversion-event/external.{"eventId":…}. Several comma-separated v1= values are accepted.

Pattern: ^v1=[0-9a-f]{64}(,\s*v1=[0-9a-f]{64})*$

Body

application/json

eventId

string

required

Opaque, unique per site, stable. The CMS mints a UUID for events it originates; another system mints its own (e.g. tenant-42:order:1234:purchase). Forwarded unchanged to every ad platform as its de-duplication key.

Maximum string length: 128

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$

Example:

"tenant-42:order:1234:purchase"

conversion

string

required

A Conversion’s id or key (GET /conversion/definitions); it must have a “Reported by another system” trigger.

Maximum string length: 128

Example:

"booking"

producer

object

required

Your system: who is posting the fact.

Show child attributes

occurredAt

string<date-time>

When it happened (not in the future). Defaults to now.

value

number

Rounded to cents. Defaults to the Conversion’s value.

Required range: x >= 0

currency

string

ISO 4217 code of value, e.g. USD.

Pattern: ^[A-Z]{3}$

Example:

"USD"

match

object

What the CMS may join the fact to a visitor with, tried strongest first: visitorId, token (fk_at), gclAu, a click ID, then emailSha256 / phoneSha256. Hashes also travel with the conversion to the platforms (see UserDataHashes for the normalization).

Show child attributes

The customer’s ad-data consent as the producer knows it. Each flag defaults to the US-friendly value when omitted. A denial trims what is sent (no contact details or browser data; Google receives CONSENT_DENIED); the conversion itself is always stored and delivered.

Show child attributes

client

object

The customer’s browser as captured WHEN THEY BOOKED (not the server confirming later). With a user agent and a page URL the fact reaches Meta as a website event; without, as system_generated. Kept only until delivery is finished, never returned.

Show child attributes

page

object

Where the customer was when it happened.

Show child attributes

Response

The stored event. created is false when this event ID was already stored with the same content.

created

boolean

required

event

object

required

One conversion occurrence. Fields the visitor’s consent did not allow are ABSENT, not empty. Never returned: the visitor’s IP address and user agent, outbox lease and retry bookkeeping.

Show child attributes

Example:

{
  "eventId": "b8f2c1de-4f5a-4c1e-9a53-0d6f2b7c1e9a",
  "conversion": {
    "id": "ckq1w2e3r4t5y6u7i8o9p0",
    "key": "quote-request",
    "title": "Quote request"
  },
  "trigger": { "type": "form", "ref": "ckformid123" },
  "source": "browser",
  "occurredAt": "2026-09-21T15:04:05.000Z",
  "recordedAt": "2026-09-21T15:04:05.412Z",
  "updatedAt": "2026-09-21T15:04:07.020Z",
  "page": {
    "url": "https://example.com/contact?gclid=Cj0KCQjw",
    "path": "/contact",
    "referrer": "https://www.google.com"
  },
  "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
  "attribution": {
    "firstTouch": {
      "at": "2026-09-20T09:12:00.000Z",
      "path": "/",
      "landingUrl": "https://example.com/?gclid=Cj0KCQjw",
      "referrerOrigin": "https://www.google.com",
      "adPlatforms": ["google"],
      "campaign": {
        "utm_source": "google",
        "utm_campaign": "spring-sale"
      },
      "clickIds": { "gclid": "Cj0KCQjw" }
    },
    "adPlatforms": ["google"],
    "campaign": {
      "utm_source": "google",
      "utm_campaign": "spring-sale"
    },
    "clickIds": { "gclid": "Cj0KCQjw" },
    "browserIds": { "_gcl_au": "1.1.1234567890.1790000000" },
    "provenance": {
      "gclid": "ourRecord",
      "_gcl_au": "platformCookie"
    }
  },
  "consent": {
    "categories": { "analytics": true, "marketing": true },
    "mode": "lenient",
    "country": "US",
    "gpc": false,
    "policyVersion": 7
  },
  "value": 50,
  "currency": "USD",
  "userData": {
    "emailSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
    "phoneSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
    "phoneDigitsSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
  },
  "submissionId": "ck9submission1",
  "delivery": {
    "google-ads": {
      "browser": "sent",
      "server": {
        "status": "sent",
        "attempts": 1,
        "sentAt": "2026-09-21T15:04:07.001Z",
        "lastAttemptAt": "2026-09-21T15:04:07.001Z"
      }
    },
    "ga4": {
      "browser": "sent",
      "server": { "status": "n/a", "attempts": 0 }
    }
  },
  "status": "active",
  "adjustments": []
}

cURL

curl --request POST \
  --url https://{host}/api/v1/conversion-event/external \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventId": "tenant-42:order:1234:purchase",
  "conversion": "purchase",
  "producer": {
    "system": "reservation",
    "ref": "booking-1234"
  }
}
'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const createExternalConversionEvent = await site.conversionEvents().createExternalConversionEvent({ eventId: 'tenant-42:order:1234:purchase', conversion: 'booking', producer: { system: 'reservation' } });

use Fetchski\AttractCmsLaravel\Facades\Attract;

$createExternalConversionEvent = Attract::conversionEvents()->createExternalConversionEvent(eventId: 'tenant-42:order:1234:purchase', conversion: 'booking', producer: ['system' => 'reservation']);

{
  "created": true,
  "event": {
    "eventId": "tenant-42:orders:1234:purchase",
    "conversion": {
      "id": "ckq1w2e3r4t5y6u7i8o9p0",
      "key": "booking",
      "title": "Booking"
    },
    "trigger": {
      "type": "external",
      "ref": "booking-1234"
    },
    "source": "external",
    "occurredAt": "2026-09-21T15:04:05.000Z",
    "recordedAt": "2026-09-21T15:04:05.412Z",
    "updatedAt": "2026-09-21T15:04:07.020Z",
    "page": {
      "url": "https://example.com/contact?gclid=Cj0KCQjw",
      "path": "/contact",
      "referrer": "https://www.google.com"
    },
    "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
    "attribution": {
      "firstTouch": {
        "at": "2026-09-20T09:12:00.000Z",
        "path": "/",
        "landingUrl": "https://example.com/?gclid=Cj0KCQjw",
        "referrerOrigin": "https://www.google.com",
        "adPlatforms": [
          "google"
        ],
        "campaign": {
          "utm_source": "google",
          "utm_campaign": "spring-sale"
        },
        "clickIds": {
          "gclid": "Cj0KCQjw"
        }
      },
      "adPlatforms": [
        "google"
      ],
      "campaign": {
        "utm_source": "google",
        "utm_campaign": "spring-sale"
      },
      "clickIds": {
        "gclid": "Cj0KCQjw"
      },
      "browserIds": {
        "_gcl_au": "1.1.1234567890.1790000000"
      },
      "provenance": {
        "gclid": "ourRecord",
        "_gcl_au": "platformCookie"
      }
    },
    "consent": {
      "categories": {
        "analytics": true,
        "marketing": true
      },
      "mode": "lenient",
      "country": "US",
      "gpc": false,
      "policyVersion": 7
    },
    "value": 3200,
    "currency": "USD",
    "userData": {
      "emailSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneDigitsSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
    },
    "submissionId": "ck9submission1",
    "delivery": {
      "google-ads": {
        "browser": "sent",
        "server": {
          "status": "sent",
          "attempts": 1,
          "sentAt": "2026-09-21T15:04:07.001Z",
          "lastAttemptAt": "2026-09-21T15:04:07.001Z"
        }
      },
      "ga4": {
        "browser": "sent",
        "server": {
          "status": "n/a",
          "attempts": 0
        }
      }
    },
    "status": "active",
    "adjustments": [],
    "producer": {
      "system": "reservation",
      "ref": "booking-1234"
    },
    "join": {
      "by": "token"
    }
  }
}

{
  "name": "invalid",
  "message": "The query is not valid.",
  "data": {
    "errors": [
      {
        "name": "invalid",
        "code": 400,
        "path": "limit",
        "message": "A whole number from 1 to 500.",
        "data": {}
      }
    ]
  }
}

{
  "name": "unauthorized",
  "message": "X-Fetchski-Signature does not match this request.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: conversions:read.",
  "data": {}
}

{
  "name": "notfound",
  "message": "No event with this ID.",
  "data": {}
}

{
  "name": "conflict",
  "message": "An event with this ID is already stored with different content.",
  "data": {
    "eventId": "tenant-42:order:1234:purchase"
  }
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": {
    "retryAfter": 12
  }
}

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Post a conversion another system saw

Authorizations

Scopes

Headers

Body

Response