Overview

OpenAI Ads is OpenAI's advertising platform, where campaigns are created and delivered across ChatGPT and the web. Advertisers measure results with the OpenAI measurement pixel, and can supplement it with server-side data through OpenAI's APIs.

The Lytics integration offers two exports:

OpenAI Ads exposes these as two separate APIs, on two hosts, with two separate credentials. Each export uses its own authorization, so if you plan to run both jobs you will create two authorizations.

Authorization

If you haven't already done so, you will need an OpenAI Ads account before you begin the process described below.

If you are new to creating authorizations in Lytics, see the Authorizations documentation for more information.

1. Select OpenAI Ads from the list of providers.
2. Select the method for authorization. Note that different methods support different job types. OpenAI Ads supports the following authorization methods:
   • OpenAI Ads API Key - Custom Audience Export
   • OpenAI Conversions API Key - Conversions API Export
3. Enter a Label to identify your authorization.
4. (Optional) Enter a Description for further context on your authorization.
5. Complete the configuration steps needed for your authorization. These steps will vary by method.
6. Click Save Authorization.

OpenAI Ads API Key

This method supports the Custom Audience Export job type only. Create an Ads API key in OpenAI Ads Manager under Settings.

Each Ads API key is scoped by OpenAI to a single ad account. Use the key belonging to the ad account you want to sync audiences to — there is no ad account to select anywhere in Lytics, because the key itself is the scope. A job configured with this authorization can only reach custom audiences on that one ad account.

1. In the Ads API Key text box, enter your OpenAI Ads API key.

When you save, Lytics verifies the key by reading the ad account it is scoped to. A key that cannot reach an ad account is rejected.

OpenAI Conversions API Key

This method supports the Conversions API Export job type only. This is a separate credential from the Ads API key, on a different host, and one cannot be substituted for the other. Find the Conversions API key on the conversions tab in OpenAI Ads Manager.

1. In the Conversions API Key text box, enter your OpenAI Conversions API key.

Lytics cannot verify this key when you save it. Every OpenAI conversions endpoint requires a Pixel ID, which is configured on the job rather than on the authorization, so the authorization is only checked for a value. If the key is wrong, the export job — not the authorization — is where the failure appears.

OpenAI Ads: Conversions API Export

Send server-side conversion events from a Lytics audience to an OpenAI pixel using the OpenAI Conversions API. Server-side events supplement the browser pixel with conversions it cannot observe — offline purchases, phone orders, back-office events — and improve campaign measurement and optimization.

Integration Details

• Implementation Type: Server-side Integration
• Implementation Technique: API Integration, Audience Trigger Integration
• Frequency: Real-time Integration
• Resulting data: Conversion events on the configured OpenAI pixel, built from Lytics user fields.

Once the job is started, it will:

1. Optionally scan the existing audience membership, building a conversion event from each user's fields according to the job's configuration.
2. Add each event to a batch. The batch is sent to OpenAI every five seconds, or when it reaches 1,000 events, whichever happens first.
3. Run continuously. As users enter or exit the Lytics audience — or as the user fields you selected under Fields to Trigger change — further events are sent.

Invalid Events Are Dropped, Not Sent

A conversions batch at OpenAI is all-or-nothing: if OpenAI rejects one event in a request, the entire request fails. There is no partial-success mode.

To keep one malformed profile from taking a whole batch of good conversions down with it, Lytics drops any user it cannot build a valid event for, and reports those users as omitted on the job. An event is dropped when:

• The event type is missing or unsupported.
• No timestamp could be determined, or no event ID could be determined.
• The event type is Custom and no custom event name was mapped or configured.
• The action source is Web and no source URL was mapped or configured.
• The event type is App Installed or App Opened and no action source was configured. OpenAI requires one for these.
• The user has no identifiers at all and no attribution reference (oppref).

If every user in a batch is dropped, the job reports that no valid events were found.

Deduplicating Against the Browser Pixel

OpenAI deduplicates on Pixel ID + event name + event ID. To have a server-side event collapse with the same conversion observed by the browser pixel, map Event ID to the Lytics field holding the same ID the pixel sends, and use the same custom event name in both places.

If Event ID is not mapped, Lytics synthesizes one from the user's ID and the event timestamp. That keeps the event valid, but it cannot match anything the pixel sent, so the conversion will be counted twice if the pixel also reports it.

Attribution References

Attribution Reference (oppref) and Browser Reference (obref) are OpenAI's click and browser identifiers, and are the strongest match signals available. Neither one reaches Lytics on its own: your site must run the OpenAI measurement pixel, and the resulting __oppref and __obref cookies must be captured into Lytics user fields through the JavaScript tag. Without them, matching relies on hashed email, phone, and the other user fields you map.

Fields

Lytics normalizes every identifier to OpenAI's documented rules before sending it. Values that are already SHA-256 hex digests are passed through unchanged.

📘

Phone numbers are normalized differently for each OpenAI export

The Conversions API wants digits only, with no +. The Custom Audience Export wants full E.164, including the +. Lytics applies the correct form for each job automatically; the same Lytics phone field can be used for both.

For fields that hold a set of values, OpenAI accepts up to three values, and Lytics sends the first three unique values in the order they appear on the profile.

The event body is built from the Event Mapping inputs:

🚧

Conversion value is sent in minor units

OpenAI requires the conversion value as a whole number of minor units, so 19.99 US dollars is sent as 1999. Use the Conversion Value Units setting to tell Lytics which units your mapped field is already in. Selecting the wrong one produces a silent 100× error in your reported conversion value — the job will not fail.

Each event type belongs to a data family that OpenAI requires the payload to declare. Lytics sets it for you; the family is shown in parentheses next to each event type in the Event Type dropdown.

An example payload:

{
    "integration_source": "lytics",
    "events": [
        {
            "id": "0473bcd3-b7d1-56c0-9049-9289d5599b95",
            "type": "order_created",
            "timestamp_ms": 1765236624000,
            "action_source": "web",
            "source_url": "https://www.example.com/checkout/complete",
            "oppref": "b1f0c2d9e7a4",
            "data": {
                "type": "contents",
                "amount": 1999,
                "currency": "USD",
                "contents": [
                    {
                        "id": "SKU-1123",
                        "name": "Trail Runner",
                        "quantity": 2
                    }
                ]
            },
            "user": {
                "emails_sha256": ["dbd8928a943dbd80caca9e33c6ff8adb8a6a32511626114d47b9048b7496fe12"],
                "phone_numbers_sha256": ["b13ce5d3de6d5b0dd1c6dbf9b3a1b8ab2a5b3c7d6e9f0a1b2c3d4e5f60718293"],
                "cities": ["portland"],
                "countries": ["US"],
                "ip_address": "192.192.1.1",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Gecko/20100101 Firefox/47.0"
            }
        }
    ]
}

Configuration

Follow these steps to set up and configure an OpenAI Ads Conversions API export job in the Lytics platform. If you are new to creating jobs in Lytics, see the Destinations documentation for more information.

1. Select OpenAI Ads from the list of providers.
2. Select the export OpenAI Ads: Conversions API Export from the list.
3. Select the OpenAI Conversions API Key authorization you would like to use, or create a new one.
4. Enter a Label to identify this job you are creating in Lytics.
5. (Optional) Enter a Description for further context on your job.
6. In the Audiences input, select the Lytics audiences that contain the users to export.
7. In the Pixel ID text box, enter the OpenAI Pixel ID these conversions belong to. Find it on the conversions tab in OpenAI Ads Manager.
8. From the Event Type input, select the OpenAI conversion event type. Select Custom to send an event name of your own.
9. (Optional) In the Custom Event Name text box, enter the event name. Required when the event type is Custom and no custom event name is mapped. Use 1 to 64 letters, digits, underscores, or hyphens, starting and ending with a letter or digit — and use the same name in the browser pixel so the two deduplicate.
10. (Optional) From the Action Source input, select where the conversion happened. Required for App Installed and App Opened events. Web events also require a source URL.
11. From the User Data Mapping input, map Lytics user fields to OpenAI user matching fields. At least one identifier must be mapped, and match rates rise with each additional one.
12. (Optional) From the Event Mapping input, map Lytics user fields to OpenAI event fields.
13. (Optional) From the Conversion Value Units input, select whether your mapped value field holds major units (dollars) or minor units (cents). Defaults to major units.
14. (Optional) From the Currency Code input, select the currency used when no currency field is mapped. Defaults to USD.
15. (Optional) In the Fallback Source URL text box, enter a URL to use for web events whose mapped Source URL field is empty.
16. (Optional) Select the Opt Out of Personalization toggle to opt these events out of future user-level personalization at OpenAI.
17. (Optional) From the Fields to Trigger input, select up to 75 user fields to trigger user change events. For any user in the exported audience, if any of the selected field values change, that user is sent to the OpenAI Conversions API.
18. (Optional) From the Audience Trigger Events input, select which type of audience trigger events to send.
19. (Optional) Select the Existing Users checkbox to immediately push users who currently exist in the selected Lytics audiences. Deselecting will only push users as they enter or leave the audience.
20. Click the Complete button to start the job.

OpenAI Ads: Custom Audience Export

Export your Lytics audiences to an OpenAI custom audience to target specific customers in your OpenAI Ads campaigns. Refine your targeting using Lytics audiences built on behavioral data, data science scores, and content affinities from across your channels.

Integration Details

• Implementation Type: Server-side Integration
• Implementation Technique: API Integration, Audience Trigger Integration
• Frequency: Batch Integration
• Resulting data: An OpenAI custom audience whose membership tracks the selected Lytics audiences.

Once the job is started, it will:

1. Create a new OpenAI custom audience, unless you selected an existing one to sync into.
2. Add the users already in the selected Lytics audiences, then keep the audience current from there.
3. As users enter the exported Lytics audience, add their identifiers to an add batch. As users exit, add their identifiers to a removal batch. Identifiers that are not already SHA-256 hashed are hashed before being added, except Google Advertising IDs, which OpenAI hashes itself.
4. Send both batches every two minutes, or once either batch reaches 2,500 identifiers, whichever happens first.
5. Run continuously, keeping the OpenAI audience in step with the Lytics audience. Users who exit the Lytics audience are always removed from the OpenAI audience.

Membership changes at OpenAI are asynchronous: OpenAI acknowledges a batch immediately and applies it in the background. Lytics waits briefly for each batch to settle so the job's synced counts reflect what OpenAI actually accepted. A batch that OpenAI reports as failed is counted as omitted on the job.

📘

OpenAI reports audience size in ranges, not exact counts

For privacy reasons, OpenAI reports matched users as a range (under_25k, 25k_100k, and so on) rather than an exact number, so Lytics cannot report how many exported users matched. OpenAI publishes 25,000 matched users as the planning threshold for inclusion targeting and bid adjustments; exclusion-only campaigns have no minimum size.

Fields

Lytics exports the following fields to OpenAI.

Each field may be scalar or a set, and may already hold SHA-256 hashed values — those are passed through unchanged. A user with no usable value in any of the three fields is skipped and counted as omitted on the job.

🚧

Do not map a pre-hashed Google Advertising ID

OpenAI lowercases and hashes advertising IDs with its own scheme, so a value that is already a SHA-256 digest can never match. Lytics skips pre-hashed values in the Mobile ID Field rather than sending a guaranteed miss.

Configuration

Follow these steps to set up and configure an OpenAI Ads custom audience export job in the Lytics platform. If you are new to creating jobs in Lytics, see the Destinations documentation for more information.

1. Select OpenAI Ads from the list of providers.
2. Select the export OpenAI Ads: Custom Audience Export from the list.
3. Select the OpenAI Ads API Key authorization you would like to use, or create a new one.
4. Enter a Label to identify this job you are creating in Lytics.
5. (Optional) Enter a Description for further context on your job.
6. In the Audiences input, select the Lytics audiences that contain the users to export.
7. (Optional) In the OpenAI Audience Name text box, enter a name for a new custom audience in OpenAI. Must be at least three characters. If left blank, the audience is named Lytics <audience name> after the Lytics audience being exported. This is ignored when you select an existing audience below.
8. (Optional) From the Existing OpenAI Custom Audience input, select an existing OpenAI custom audience to sync into instead of creating a new one. Only audiences on the ad account your authorization is scoped to are listed.
9. (Optional) From the Email Field input, select the field that contains the user's email.
10. (Optional) From the Phone Field input, select the field that contains the user's phone number.
11. (Optional) From the Mobile ID Field input, select the field that contains the user's Google Advertising ID.
12. Click the Complete button to start the job.

At least one of Email Field, Phone Field, or Mobile ID Field must be selected, and mapping more than one raises your match rate.