OpenAI Ads CAPI
This integration is currently in beta. Contact your MetaRouter support team to get started.
What Is OpenAI?
OpenAI is an artificial intelligence research and deployment company that develops and operates a range of AI products and services. Through its advertising offerings, OpenAI provides a Conversions API (CAPI) that allows advertisers to measure and attribute conversions resulting from their campaigns. This integration captures a URL-based identifier and forwards it to OpenAI's server-side endpoint to support accurate conversion measurement and attribution.
Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web
Event Scope: Full-Funnel Events
Capabilities
- Sends standardized conversion and engagement events directly to OpenAI via the Events API.
- Supports batched event delivery in a single request.
- Captures the OpenAI privacy-preserving identifier (
oppref) for attribution. - Enriches events with hashed user identifiers and location attributes for matching.
- Supports full-funnel events, including page, product, checkout, and order activity.
Considerations
- This integration requires Conversion API keys, not a general advertising account key. These can be found under the Conversion Keys section.
- Each event's timestamp must fall within a valid window: events more than 7 days in the past or more than 10 minutes in the future are rejected. A single out-of-window event will cause the entire batch to fail.
- The
contents_viewedevent type is mapped to Product Viewed by default. Other event types (such as Cart Viewed or Product List Viewed) can be mapped to it. - User country must be formatted as an ISO 3166-1 country code.
- Currency values must use ISO 4217 uppercase codes (e.g.,
USD) and are required whenever a monetary amount is present at the event or item level. - Monetary amounts must be sent as integers in the currency's lowest denomination (e.g., cents).
- A page URL is required when the action source is web.
- The event type must be one of the supported event type values.
- The data object type must match the allowed data object for the event type.
- Hashed email and external identifiers must be SHA-256 hashes of normalized (lowercase, trimmed) values.
- No rate limits are documented for this integration.
Limitations
- A batch may contain up to 1000 events, but if any single event fails validation, the entire batch is dropped. By default, this starter kit sends events in batches of 10 to limit the impact of a failed batch.
Identity Sync
- Sync Available: Yes
- Required for Starter Kit: Yes
- Prerequisites: None
- Documentation: See OpenAI Sync Documentation
Sync Details
- Captures the OpenAI privacy-preserving identifier (
oppref) from the URL. - Stores the identifier in first-party storage for a configurable cookie lifetime.
- Appends the resolved identifier to server-side events under
context.providers.openAI. - Used to improve attribution for conversions sent to OpenAI.
Starter Kit Setup Guide
1. Deploy the OpenAI Sync
- To collect the sync values (e.g.,
oppref), you must implement an OpenAI ID sync. Refer to the following documentation to complete the setup: OpenAI - ID Sync Guide.
2. Gather Credentials
- Ask vendor representatives for the following credentials:
API_KEY:A Conversion API key. You can find or generate this under Tools > Conversions > Conversion Keys.PIXEL_ID:Your OpenAI Pixel ID. You can find this under your Data Source name in the Conversions tab.
3. Add an OpenAI Integration
- From the integration library, add an OpenAI integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|---|
API_KEY | Conversion API key used to authenticate API requests via a Bearer token. |
PIXEL_ID | Pixel identifier appended to the endpoint and used to associate events with your account. |
4. Configure Event Mapping
- MetaRouter provides all of the event mappings that OpenAI integrations typically require. You may add custom events, parameters, or mappings in accordance with OpenAI's API documentation.
5. Deploy to Pipeline
- In the Pipelines tab, add your OpenAI integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
Event Mappings
Global
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|---|---|
id Required | String: Unique event identifier used with type for deduplication. | messageId |
timestamp_ms Required | Integer: Event timestamp in milliseconds. Must be within 7 days past and 10 minutes future. | Expression – converts timestamp to milliseconds |
action_source | String: Source of the action. | Enrichment – 'web' |
source_url Required | String: Advertiser page URL. Required when action_source is web. | context.page.url |
oppref | String: OpenAI privacy-preserving identifier captured by the sync. | context.providers.openAI.oppref |
user.email_sha256 | String: SHA-256 hash of the normalized, lowercased email. | Expression – hashes traits.email after normalization |
user.external_id_sha256 | String: SHA-256 hash of the anonymous ID as a pseudonymous external identifier. | Expression – hashes anonymousId |
user.country | String: ISO 3166-1 country code derived from user address. | Expression – converts traits.address.country to ISO country |
user.city | String: City of the user. | traits.address.city |
user.zip_code | String: Zip code of the user. | traits.address.postalCode |
user.ip_address | String: IP address of the user. | context.ip |
user.user_agent | String: Browser or device user agent. | context.userAgent |
Event Specific
Page
| Output Key | Description | Expected Input |
|---|---|---|
type Required | String: Event type for page activity. | Enrichment – 'page_viewed' |
data.type Required | String: Data object type for the event. | Enrichment – 'contents' |
data.contents | Array: Content object describing the viewed page. | Expression – builds content from properties.title |
Product Viewed
| Output Key | Description | Expected Input |
|---|---|---|
type Required | String: Event type for product view activity. | Enrichment – 'contents_viewed' |
data.type Required | String: Data object type for the event. | Enrichment – 'contents' |
data.currency | String: ISO 4217 uppercase currency code. | properties.currency (uppercase) |
data.contents | Array: Content details for the viewed product. | Expression – builds content from properties.product_id, name, price, quantity |
Product Added
| Output Key | Description | Expected Input |
|---|---|---|
type Required | String: Event type for add-to-cart activity. | Enrichment – 'items_added' |
data.type Required | String: Data object type for the event. | Enrichment – 'contents' |
data.currency | String: ISO 4217 uppercase currency code. | properties.currency (uppercase, default USD) |
data.contents | Array: Content details for the added product. | Expression – builds content from properties.product_id, name, price, quantity |
Checkout Started
| Output Key | Description | Expected Input |
|---|---|---|
type Required | String: Event type for checkout start activity. | Enrichment – 'checkout_started' |
data.type Required | String: Data object type for the event. | Enrichment – 'contents' |
data.currency | String: ISO 4217 uppercase currency code. | properties.currency (uppercase) |
data.contents | Array: Content details for all checkout items. | Expression – maps each item in properties.products to content fields |
Order Completed
| Output Key | Description | Expected Input |
|---|---|---|
type Required | String: Event type for purchase activity. | Enrichment – 'order_created' |
data.type Required | String: Data object type for the event. | Enrichment – 'contents' |
data.currency | String: ISO 4217 uppercase currency code. | properties.currency (uppercase) |
data.amount | Integer: Total order value in the currency's lowest denomination. | Expression – totals properties.products and converts to integer |
data.contents | Array: Content details for all purchased items. | Expression – maps each item in properties.products to content fields |
Required & Recommended Identifiers
These identifiers must be mapped to OpenAI in order for successful user matching to occur. Without these IDs, any events sent to OpenAI may not be accurately reflected in reporting.
Attribute | Example | Sync Injector Required? |
|---|---|---|
|
| Yes |
|
| No |
|
| No |
|
| No |
|
| No |
Integration Validation
Under Tools > Conversions, you can validate your events in two areas:
- Conversion Events: View the general event count per event.
- Event Stream: Enable polling to see more detail on incoming events, including the JSON payload and timestamps.
Please ask your OpenAI Ads representative to confirm that event and user data are being received and processed on their end as well.