OpenAI Ads Conversions API

Send server-side conversion events to OpenAI Ads using the Conversions API.

info

API Documentation: OpenAI Conversions API | Supported Events Reference

Setup Guide

To configure OpenAI Ads Conversions API as a destination, you'll need the following:

1. Conversions API Key - In your OpenAI Ads Manager account, open the conversions tab and generate a Conversions API key.
2. Pixel ID - In the same conversions area, copy the Pixel ID you want this stream to target.
3. Event identifiers - Reuse the same event identifier across browser and server events when you need deduplication between the JavaScript pixel and the Conversions API.
4. oppref capture - If you collect OpenAI's privacy-preserving identifier client-side, pass it through to your server and include it in the event payload when available.

Authentication

This connector authenticates using a Bearer token.

• API key: Used as Authorization: Bearer <api_key> for all requests.
• During connection/login validation, the connector verifies the API key by calling the OpenAI Ads ad account endpoint.

Configuration

Destination-level settings

These settings are configured on the destination connector itself:

Field	Type	Required	Description
api_key	string	Yes	OpenAI Ads API key used to authenticate requests.
continue_on_errors	boolean	Yes	If true, the connector will log errors and continue processing subsequent records/batches when possible. If false, the connector will fail the sync on errors.

Stream-level settings

These settings are configured per stream:

Field	Type	Required	Description
pixel_id	string	Yes	The OpenAI Ads Pixel ID to associate events with.

Event Model

Each record sent to this destination must represent a single event.

Required top-level fields

Field	Type	Required	Description
type	string	Yes	Event type name. See Supported event types.
timestamp_ms	integer	Yes	Event timestamp in milliseconds since epoch. Must be within allowed time bounds.
data	object	Yes	Event payload. Must match the expected data type for the event type.
user	object	No	User context object (must be a JSON object if provided).
action_source	string	No	Source of the action (for example, web). If action_source is web, then source_url is required.
source_url	string	No	URL where the event occurred. Required when action_source is web.
custom_event_name	string	No	Only allowed when type is custom. Required when type is custom.

Supported event types

The connector supports the following built-in event type values:

• appointment_scheduled
• checkout_started
• contents_viewed
• custom
• items_added
• lead_created
• order_created
• page_viewed
• registration_completed
• subscription_created
• trial_started

Custom events

If type is custom:

• custom_event_name is required
• custom_event_name must pass connector validation (for example, format/character constraints)
• custom_event_name is not allowed for non-custom event types

Timestamp requirements

The connector validates timestamp_ms:

• Events must not be older than 7 days
• Events must not be too far in the future (up to 10 minutes of clock skew is allowed)

If a record fails timestamp validation, it will be rejected.

Data object requirements

The data object is required and must be a JSON object. The connector validates that the data object matches the expected data category for the given type:

Event type	Expected data.type
appointment_scheduled, lead_created, registration_completed	customer_action
checkout_started, contents_viewed, items_added, order_created, page_viewed	contents
subscription_created, trial_started	plan_enrollment
custom	custom

If the data object does not match what the connector expects for the event type, the record will be rejected.

Delivery Behavior

• Events are sent to https://bzr.openai.com/v1/events?pid=<pixel_id> in batches of up to 1,000 events per request.
• The connector uses concurrent workers to send batches efficiently.
• Null values are stripped from outgoing event objects.
• If one event in a batch fails, the full batch fails.

Data Contract Information

info

Your source dataset must be compatible with the parameter requirements of OpenAI's Conversions API. This includes using the documented event names and data.type combinations, sending amounts as integers in the currency's lowest denomination, and including currency whenever amount is present.

The optional user object is exposed here as a raw JSON field. Extract validates only that it is a JSON object and then forwards it without enforcing a field-level schema.

data.contents is provided as a JSON field and validated by the connector at runtime as an array of OpenAI content objects.

Loading ....