Skip to main content
When you finish, one Datalyr event reaches the OpenAI Ads Conversions API and returns HTTP 200.

​
Before you start

Treat the API key as a secret. Do not paste it into a browser console, a screenshot, or a public issue.

​
Connect OpenAI Ads

1

Open Sources

Open Sources. Find the OpenAI Ads card.
2

Paste the credentials

Select connect. Fill API key. Fill Pixel ID.
3

Save

Select connect in the dialog.
We fire a validate_only: true request against your pixel before we save it, so bad credentials fail here rather than at your first live conversion.

​
Create the rule

1

Open the editor

Open Conversions. Select manage rules. Select new rule.
2

Set the trigger

Fill rule name. Pick the trigger event. Pick OpenAI as target platform.
3

Pick the pixel

Pick the pixel under OpenAI Pixel. Select next.
4

Map the event

Pick the platform standard event. Set value to dynamic for revenue events. Set currency.
5

Save

Select save. Enable the rule.

​
Reference

We post to POST https://bzr.openai.com/v1/events?pid={pixel_id} with an Authorization: Bearer header. The pixel goes on the URL, never in the body. We abort the request after 15 seconds.

​
Event types

Each type forces a data.type shape. That shape decides which fields OpenAI accepts. A custom type also carries custom_event_name. We lowercase it and force it to match ^[a-z0-9_-]{1,64}$.

​
Money

OpenAI takes amounts in the currency’s minor unit, so we multiply by the per-currency factor. data.currency is required whenever data.amount is present. We write the rule’s currency, else USD.

​
action_source

We send one of web, mobile_app, offline, physical_store, phone_call, email, other. A web event with no resolvable page URL degrades to other, because OpenAI requires source_url on web.

​
Timestamps

timestamp_ms is epoch milliseconds. OpenAI accepts a window of 7 days into the past and 10 minutes into the future. We clamp a future timestamp to now, and skip an older event with the reason timestamp_out_of_window.

​
Attribution and identity

oppref is the OpenAI click ID. We read it from the oppref URL parameter, the __oppref first-party cookie, and the attribution history of linked visitors. The lookup window is 7 days. The user object is off by default. Turn it on per rule with config.send_user_data. OpenAI Ads accepts no phone field, so we never send one. After a marketing denial, we set opt_out: true and send no user object and no oppref.

​
Deduplication

We send id, the same UUID the browser pixel fires with, and OpenAI collapses the pair into one conversion.

​
Verify

  1. Open Conversions. Select manage rules. Open your rule.
  2. Select send test event. The request carries validate_only: true.
  3. Confirm the delivery row shows HTTP 200 and no error in the body.
  4. Trigger one real event.
  5. Confirm the rule’s sent count went up by 1.

​
When it does not work

​
Next