Conversions API

A browser pixel misses a lot: blocked scripts, purchases that close on the phone, deals that sign weeks later in your CRM. Server-side conversions fill the gap. You send the event from your backend once, in one shape, and Pozy delivers it to the ad network's own conversions API, hashed and formatted the way that network expects. Networks then attribute and optimize on it next to what the pixel saw.

#Send your first event

curl https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/conversion-destinations \
  -H "Authorization: Bearer $POZY_API_KEY"

{
  "platform": "metaads",
  "destinations": [
    { "id": "1729525464415281", "name": "Acme website pixel", "status": "active", "adAccountId": "act_1234567890" }
  ]
}

curl -X POST https://api.pozy.ai/v1/ads/conversions \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "destinationId": "1729525464415281",
    "events": [{
      "eventName": "Purchase",
      "eventTime": 1804064400,
      "eventId": "order_1042",
      "value": 129.99,
      "currency": "USD",
      "actionSource": "web",
      "sourceUrl": "https://shop.example.com/checkout/thanks",
      "user": {
        "email": "jane@example.com",
        "phone": "+14155551234",
        "ipAddress": "203.0.113.7",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5)",
        "clickIds": { "fbc": "fb.1.1804060000.IwAR2...", "fbp": "fb.1.1803990000.1234567890" }
      },
      "items": [{ "id": "sku-981", "name": "Linen throw", "price": 64.99, "quantity": 2 }]
    }]
  }'

const res = await fetch("https://api.pozy.ai/v1/ads/conversions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "66b2e19d8c3f5a7e9d0b1c2d",
    destinationId: "1729525464415281",
    events: [
      {
        eventName: "Purchase",
        eventTime: Math.floor(Date.now() / 1000),
        eventId: "order_1042",
        value: 129.99,
        currency: "USD",
        actionSource: "web",
        sourceUrl: "https://shop.example.com/checkout/thanks",
        user: {
          email: "jane@example.com",
          phone: "+14155551234",
          ipAddress: "203.0.113.7",
          userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5)",
          clickIds: { fbc: "fb.1.1804060000.IwAR2...", fbp: "fb.1.1803990000.1234567890" },
        },
        items: [{ id: "sku-981", name: "Linen throw", price: 64.99, quantity: 2 }],
      },
    ],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
if (data.eventsFailed) console.warn(data.failures);

import os, time, requests

resp = requests.post(
    "https://api.pozy.ai/v1/ads/conversions",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
        "destinationId": "1729525464415281",
        "events": [{
            "eventName": "Purchase",
            "eventTime": int(time.time()),
            "eventId": "order_1042",
            "value": 129.99,
            "currency": "USD",
            "actionSource": "web",
            "sourceUrl": "https://shop.example.com/checkout/thanks",
            "user": {
                "email": "jane@example.com",
                "phone": "+14155551234",
                "ipAddress": "203.0.113.7",
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5)",
                "clickIds": {"fbc": "fb.1.1804060000.IwAR2...", "fbp": "fb.1.1803990000.1234567890"},
            },
            "items": [{"id": "sku-981", "name": "Linen throw", "price": 64.99, "quantity": 2}],
        }],
    },
)
body = resp.json()
print(body["eventsReceived"], body["failures"])

{
  "platform": "metaads",
  "eventsReceived": 1,
  "eventsFailed": 0,
  "failures": [],
  "traceId": "AbCdEf123456"
}

#The event shape

At the request root, testCode sends the batch to the network's test tools, and consent carries the person's choices. Both are explained below.

#Match keys

The more identifiers you send, the more conversions a network can tie back to an ad. Send them in plain text. Pozy normalizes and hashes personal data with SHA-256 to each network's spec before anything leaves Pozy, including Google's rule that strips dots and +suffix from Gmail addresses.

ipAddress, userAgent and click ids are sent unhashed, as the networks require. LinkedIn takes externalId in plain text too.

Minimum identity per network:

Events missing the minimum are reported in failures[] (for example INVALID_EVENT or MISSING_IDENTITY) and the rest of the batch still goes.

#Deduplicate against the pixel

Most sites send the same purchase from the browser pixel and from the server. Use the same eventId in both places and the network counts it once.

#Event names per network

#Offline and CRM conversions

Set actionSource to where it happened and send the identifiers you have from the CRM.

• Meta: offline, crm, phone_call and system_generated are all accepted on the same pixel.
• Google Ads: create a conversion action for uploads (below), then send events with a gclid when you kept one, or a hashed email or phone when you did not.
• LinkedIn: send to a conversion rule. eventName does not matter; the rule's type does.
• TikTok: the only path through this endpoint. destinationId is an Offline Event Set and each event needs an email or phone.

#Create a destination for uploads

POST /v1/accounts/{accountId}/conversion-destinations creates one on Google Ads and LinkedIn.

curl -X POST https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/conversion-destinations \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "adAccountId": "1234567890", "name": "Offline purchase", "type": "Purchase" }'

• Google: type is a standard name or a Google category (PURCHASE, SUBSCRIBE_PAID, SIGNUP, IMPORTED_LEAD, BOOK_APPOINTMENT). The same name again returns the existing action; the same name with a different category returns 409 idempotency_conflict. countingType (MANY_PER_CLICK by default) and primaryForGoal (default false, so it records without driving bids) are Google-only.
• LinkedIn: a rule binds a type to the destination. By default it attaches to every campaign in the ad account (autoAssociationType: "ALL_CAMPAIGNS"); OBJECTIVE_BASED attaches only matching campaigns and NONE lets you manage it with the associations endpoints. Click and view windows default to 30 and 7 days and take 1, 7, 30, 90 or 365. Creating a rule is not idempotent.

On LinkedIn, GET .../conversion-destinations/{destinationId}/metrics reads post-click and view-through conversions and value back per rule, with granularity of ALL, DAILY, MONTHLY or YEARLY.

#Correct a conversion on Google Ads

POST /v1/ads/conversions/adjustments changes conversions you already uploaded. Google Ads is the only network with this.

Identify the original with orderId, or gclid plus conversionTime. adjustmentTime is Unix seconds.

#Send once, deliver everywhere

When the same purchase should reach every network a customer advertises on, use the profile-level event stream instead of calling each destination.

curl -X POST https://api.pozy.ai/v1/events/destinations \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "66b2e19d8c3f5a7e9d0b1c2a", "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "destinationId": "1729525464415281", "eventNames": ["Purchase", "Lead"] }'

• One destination failing never blocks the others. Each reports its own result.
• Pozy stores email, phone and externalId only as SHA-256 hashes, and keeps only the origin, path and attribution parameters of sourceUrl.
• Events sent with testCode are forwarded but not stored.

#Test mode

testCode at the request root lets you check an integration without polluting live data.

Remove testCode for production traffic. An event sent with it is not counted on Pinterest.

#Consent

The root consent object takes adUserData and adPersonalization, each GRANTED or DENIED. Split batches by consent state rather than by network.

#Match quality

GET /v1/ads/conversions/quality?accountId=...&destinationId=... reads the network's own scoring of your server events, without opening its dashboard.

• Meta: Event Match Quality per event name, compositeScore from 0 to 10, coverage per identifier in matchKeys, and how well server events overlap the pixel. Web events only.
• Pinterest: Event Quality Score over the last 14 days, per event name, with matchKeys and pixel overlap. There is no composite score.

#Batching and limits

Pozy splits large batches for you. What happens when one event is bad depends on the network:

Google can take up to 3 hours to show an uploaded conversion. Reddit accepts events up to 7 days old.

#Permissions and reconnects

Some networks grant the conversions permission separately. A connection made before that permission existed has to go through the connect flow again.

#Endpoints

Meta custom conversions (rules over pixel events) live on the ad account: GET and POST /v1/accounts/{accountId}/custom-conversions.