OpenAI Conversions API
Overview
Section titled “Overview”OpenAI Conversions API reports website conversions to OpenAI, so ChatGPT Ads campaigns can be measured and optimized against what happened after someone clicked.
Because the events come from your server rather than the visitor’s browser, they arrive whether or not the browser pixel fired. OpenAI describes the Conversions API as the more reliable of the two sources and recommends using it where you can.
It complements the OpenAI pixel rather than replacing it. Running both is the usual setup, so the same event ID has to travel on both paths for OpenAI to reconcile them.
For conversions recorded in your own systems rather than on the website, use OpenAI Offline Conversions API.
Supported sources
Section titled “Supported sources”Prerequisites
Section titled “Prerequisites”Before connecting OpenAI Conversions API, make sure you have:
- A ChatGPT Ads account with access to OpenAI Ads Manager.
- Brand review approved on that ad account. An account cannot serve ads until it is, and conversions reported against a campaign that is not running will not show anything useful.
- A Pixel ID and a Conversions API key, both provisioned from the conversions tab in Ads Manager.
- Pixel and Conversions API key creation enabled on the ad account. This is gated by OpenAI, so if the conversions tab will not create either one, contact your OpenAI representative.
- A website source connected in the same Datahash project.
- A Datahash Studio account with the target project selected.
ChatGPT Ads is a beta product and Ads Manager is not available everywhere. At the time of writing OpenAI lists Australia, Canada, Japan, Korea, New Zealand, the United Kingdom and the United States. Check OpenAI’s availability page rather than this one, since the list is expanding.
Authentication
Section titled “Authentication”In Studio, open Destinations, find OpenAI, and click the Conversions API tile. This connector uses credentials rather than a sign-in.
- Enter the Pixel ID.
- Enter the API Key.
- Click Validate Credentials. The pair is checked against OpenAI before the setup completes.
| Field | Where to find it |
|---|---|
| Pixel ID | Provision it from the conversions tab in OpenAI Ads Manager, where a pixel is created as a data source. Ads Manager shows two values against a data source; the Pixel ID is the one used for sending events, not the internal source ID. |
| API Key | Provision it from the same conversions tab. This is the Conversions API key, which is not the same thing as an OpenAI platform API key used for model access, and not the same as the Ads API key used for campaign management. Only the Conversions API key will authenticate here. |
If the conversions tab will not let you create a pixel or a key, the feature is not yet enabled on your ad account. That is a permission OpenAI grants, so it needs raising with your OpenAI representative rather than retried.
Manage instance
Section titled “Manage instance”To add another, open Manage Instances and click Add Instance. To change one, open it from Manage Instances, use the menu in the top right and choose Edit, update the fields and click Finish. Cancel keeps the previous configuration running, so updates apply only after you finish.
Data & identifiers
Section titled “Data & identifiers”Signals sends the fields your source maps. Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach OpenAI.
Required
Section titled “Required”| Field | When it is required |
|---|---|
| Event ID | Always. Your own unique reference for the event. It is also what OpenAI matches on to discard duplicates. |
| Event name | Always. It has to resolve to one of the event names OpenAI accepts. See Configuration. |
| Event time | Always. It has to fall within the last seven days and no more than ten minutes in the future. |
| Action source | Always. Set during configuration rather than per record. |
Recommended
Section titled “Recommended”These are the identifiers OpenAI uses to match a conversion to someone who saw an ad. Email and external ID are hashed; the rest are sent as they are.
| Field | Format |
|---|---|
| Email address | One address. Trimmed and lowercased before hashing. |
| External ID | A stable pseudonymous ID of your own, such as a customer number. Hashed. |
| Country | Two-letter ISO 3166-1 code. |
| City | Trimmed and lowercased. |
| Postcode | Letters, numbers, spaces or hyphens. |
| Client IP address | IPv4 or IPv6. |
| Client user agent | The browser user agent string. |
OpenAI does not accept a phone number, in raw or hashed form. It is prohibited rather than merely unsupported, so there is no point mapping one. Email and external ID are the two identifiers worth getting right.
There is one identifier specific to OpenAI worth knowing about. When someone clicks an ad in ChatGPT, OpenAI appends a click reference called oppref to the landing page URL, and the browser pixel stores it in a first-party cookie. The server side does not capture it for you. If you can carry that value through to the record you send, matching improves considerably; if you cannot, the other identifiers still work.
The full field specification is published by OpenAI at developers.openai.com/ads/conversions-api, and it is the authority on what is accepted rather than this page.
Best practices
Section titled “Best practices”- Send the same event ID from the pixel and from the server for any conversion both will report. It is the only thing that stops the same purchase being counted twice.
- Use OpenAI’s own event names rather than your internal ones. A conversion that does not match the event configured on the campaign is accepted and then reports as zero, which is the hardest kind of problem to spot.
- Map email and external ID. They are the two identifiers that drive matching, and phone is not accepted at all.
- Carry the oppref click reference through to the conversion if your site can. The pixel captures it automatically, the server does not.
- Keep the API key server side and rotate it if it is ever exposed. OpenAI shows it once at creation.
- Allow a day or two before judging the numbers. OpenAI states that attributed conversions can take 24 to 48 hours to appear in Ads Manager.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”Validate Credentials fails. Check the Pixel ID is the sending value from the conversions tab rather than the internal source ID, and that the key is a Conversions API key rather than a platform or Ads API key. The three are not interchangeable.
The conversions tab will not create a pixel or a key. The feature is not enabled on your ad account. OpenAI gates it, so contact your OpenAI representative.
Events are accepted but Ads Manager shows zero. The event name almost certainly does not match the conversion configured on the campaign. Matching is on the event name itself, not on a display name, and past events will not backfill once you fix it.
Conversions are counted twice. The pixel and the server are sending different event IDs for the same conversion.
Nothing is arriving. Confirm a source is connected in the same project and sending. A valid destination on its own produces nothing.
Match rates are low. Check email formatting at source before it is hashed, and add external ID. There is no phone number to fall back on with this destination.
Delivery stopped. The API key may have been revoked or the pixel deleted in Ads Manager. Provision a fresh key and revalidate.