Event

The OpenAI Conversions API lets advertisers send conversion events from their servers to OpenAI to measure campaign performance and optimize campaigns for conversions. The mParticle event integration forwards your app, web, and server-to-server events to the OpenAI Conversions API, so you can send conversions to OpenAI without building and maintaining your own server-side integration.

Prerequisites

To set up the OpenAI event integration, you need:

• An OpenAI Ads Manager account.
• An OpenAI Pixel ID, from the conversions tab of OpenAI Ads Manager.
• An OpenAI Conversion Key. To generate one, click the key icon in the top-right corner of OpenAI Ads Manager.

Setup

1. Create an OpenAI output configuration

1. In mParticle, navigate to Setup > Outputs.
2. Click Add Output and select OpenAI.
3. Enter a descriptive Configuration Name.
4. Enter your Pixel ID: the pixel ID from the conversions tab of OpenAI Ads Manager.
5. Enter your Conversion Key: the key you generated from the key icon in OpenAI Ads Manager.
6. Click Save.

2. Connect a data input to OpenAI

A connection links one platform input (such as your iOS app, Android app, or web property) to this output configuration. Each connection is independent and can be configured with its own Connection Settings, so you can use a different action source, external identity type, or consent mapping per input.

To connect an input:

1. In mParticle, navigate to Connections and select the input you want to connect to.
2. Click Connect Output and find OpenAI in the output list.
3. Select an Action Source: where the conversions on this connection occur. If you select Web, every event must include a source URL. See Source URL. For iOS, Android, and tvOS connections, select Mobile App.
4. (Optional) Enable Forward Location Attributes to send country, city, and postal code for conversion matching.
5. (Optional) Enable Forward Device Info to send the IP address and user agent for conversion matching.
6. (Optional) Enable Enrich with IP Address to fill in a missing IP address with the user’s most recently seen IP address. Requires Forward Device Info. See Enrich with IP Address.
7. (Optional) Enable Validate Only while you are testing the connection. OpenAI validates events without saving them. Disable this setting before you go live.
8. (Optional) Select an External Identity Type: the mParticle identity to send to OpenAI as the external ID. Defaults to Customer ID. Select None to send no external ID.
9. (Optional) Select a User Data Consent Mapping: the consent purpose used to set OpenAI’s opt_out flag. See Consent.
10. (Optional) Disable Send Custom Event Attributes to send standard event data only. See Custom attributes.
11. Click Add Connection.

Repeat for each platform input you want to forward to OpenAI.

Supported platforms

• iOS
• Android
• tvOS
• Web
• Custom Feed (server-to-server)

Supported identities

OpenAI uses identities and other user data to match conversions to people who saw or interacted with an ad. mParticle sends these fields in the user object of each event. All fields are optional: mParticle forwards events to OpenAI even when no identity is present. OpenAI can also attribute conversions using the OpenAI attribution identifier (oppref) alone. See Custom flags.

OpenAI field	mParticle source	When it’s sent
phone_numbers_sha256	Mobile Number, Phone Number 2, and Phone Number 3 identities, and the $Mobile user attribute	Automatically when present. Up to three unique phone numbers are sent.
emails_sha256	Email identity	Automatically when present.
external_ids_sha256	The identity selected in the External Identity Type connection setting (Customer ID by default)	When the selected identity is present. Not sent when External Identity Type is set to None.
first_names_sha256	$FirstName user attribute	Automatically when present.
last_names_sha256	$LastName user attribute	Automatically when present.
postal_codes	$Zip user attribute	Requires Forward Location Attributes.
cities	$City user attribute	Requires Forward Location Attributes.
countries	$Country user attribute	Requires Forward Location Attributes.
android_advertising_id	Google Advertising ID (GAID)	Automatically when present.
obref	OpenAI.Obref custom flag	When the custom flag is set. See Custom flags.
ip_address	IP address collected by mParticle	Requires Forward Device Info. See also Enrich with IP Address.
user_agent	User agent collected by mParticle	Requires Forward Device Info.

mParticle normalizes and hashes phone numbers, emails, external IDs, and names before sending them. See Data processing notes.

Supported event types

mParticle forwards the following event types to OpenAI:

• Commerce Event
• Screen View
• Application State Transition (iOS, Android, and tvOS only)
• Custom Event (only when mapped with a custom mapping)

Native event mappings

mParticle maps the following events to OpenAI event types automatically. You don’t need to configure anything for these events.

mParticle event	OpenAI event type	OpenAI data.type
Commerce Event: View Detail	contents_viewed	contents
Commerce Event: Add to Cart	items_added	contents
Commerce Event: Checkout	checkout_started	contents
Commerce Event: Purchase	order_created	contents
Screen View	page_viewed	contents
Application State Transition: Install	app_installed	customer_action
Application State Transition: Initialized, Upgrade, or Foreground	app_opened	customer_action

Notes on native mappings:

• Other commerce event actions (for example, Remove from Cart, Refund, Add to Wishlist, and promotion or impression events) are not forwarded.
• Application state transitions are forwarded only from iOS, Android, and tvOS inputs. Background and exit transitions are not forwarded. OpenAI only accepts app_installed and app_opened from mobile apps, so mParticle always sends these events with action_source set to mobile_app, regardless of the Action Source connection setting.

Custom mappings

Use custom mappings to send mParticle custom events to OpenAI. Custom events are forwarded only when you map them; unmapped custom events aren’t sent. In your OpenAI connection, open the Custom Mappings tab, select an OpenAI event, and map an mParticle event to it. For more information, see Custom Mappings.

Map an event to one of OpenAI’s standard events when one fits. To send an event that doesn’t match a standard event, map it to Custom.

OpenAI event (Custom Mappings tab)	OpenAI event type	OpenAI data.type
Appointment Scheduled	appointment_scheduled	customer_action
Lead Created	lead_created	customer_action
Registration Completed	registration_completed	customer_action
Subscription Created	subscription_created	plan_enrollment
Trial Started	trial_started	plan_enrollment
Page Viewed	page_viewed	contents
Checkout Started	checkout_started	contents
Contents Viewed	contents_viewed	contents
Items Added	items_added	contents
Order Created	order_created	contents
App Installed	app_installed	customer_action
App Opened	app_opened	customer_action
Custom	custom	custom

Each mapped event has these optional mapping parameters:

Parameter	OpenAI field	Available on	Description
Source URL	source_url	All events	The page URL where the conversion occurred. Required by OpenAI when the action source is web.
OpenAI Attribution ID	oppref	All events	The OpenAI attribution identifier, forwarded without modification.
Custom Event Name	custom_event_name	Custom	The name OpenAI records for the custom event. If you don’t map it, mParticle uses the mParticle event name. See Custom event names.

Custom event names

OpenAI requires every custom event to have a custom_event_name of 1 to 64 lowercase letters, digits, underscores, or hyphens that starts and ends with a letter or digit, and that isn’t one of OpenAI’s standard event names. mParticle normalizes the name before sending it:

1. Converts the name to lowercase.
2. Replaces each run of unsupported characters (including spaces) with a single underscore.
3. Removes leading and trailing underscores and hyphens.
4. Truncates the name to 64 characters, then removes any underscores or hyphens left at the end.

For example, Add Payment Method! is sent as add_payment_method: the spaces become underscores and the ! is removed.

If nothing valid remains after normalization, or if the result matches a standard OpenAI event name (for example, lead_created), mParticle doesn’t forward the event and reports it as unable to forward.

Custom attributes

When the Send Custom Event Attributes connection setting is enabled (the default), mParticle sends all of the custom attributes on events mapped to Custom (data.type of custom) to OpenAI. Each attribute is added to the event’s data object as a key-value pair, using the attribute name as the key. Custom attributes aren’t sent for any other OpenAI event type.

mParticle skips two kinds of attributes:

• Attributes named type, amount, currency, contents, or plan_id, because these names are reserved for OpenAI’s own data fields.
• Attributes you select for the Source URL, OpenAI Attribution ID, or Custom Event Name parameters on the Custom Mappings tab. mParticle sends these values in the event’s source_url, oppref, and custom_event_name fields instead, so they aren’t repeated in data.

To send standard event data only, disable the Send Custom Event Attributes connection setting. To exclude specific attributes while sending the rest, use platform filters or feed filters.

Event data mapping

Event fields

OpenAI field	mParticle source	Notes
id	OpenAI.EventId custom flag, then the source message ID, then the mParticle event ID	See Deduplication.
type	Native mapping or custom mapping	See Supported event types.
timestamp_ms	Event timestamp	See Data processing notes for the accepted time window.
custom_event_name	Custom Event Name mapping parameter, or the mParticle event name	custom events only. See Custom event names.
action_source	Action Source connection setting	Always mobile_app for app_installed and app_opened.
source_url	See Source URL
oppref	OpenAI.Oppref custom flag, then the OpenAI Attribution ID mapping parameter
opt_out	User Data Consent Mapping connection setting	See Consent.
user	User identities, user attributes, and device info	See Supported identities.
data	Event data	See Commerce data and Custom attributes.

Commerce data

For native commerce event mappings, mParticle sends the following fields in the data object:

OpenAI field	mParticle source	Notes
data.amount	Product action total amount	If the total amount is missing or zero, mParticle uses the sum of each product’s price × quantity. Sent as an integer in the currency’s minor unit.
data.currency	Currency code	Sent only when data.amount is sent.
data.contents[].id	Product ID (SKU)
data.contents[].name	Product name
data.contents[].content_type	product	Always set to product.
data.contents[].quantity	Product quantity	Rounded to a whole number. Not sent if zero or less.
data.contents[].amount	Product price	Unit price as an integer in the currency’s minor unit.
data.contents[].currency	Currency code	Sent only when data.contents[].amount is sent.

OpenAI requires monetary values as integers in the currency’s minor unit. mParticle converts decimal amounts using the ISO 4217 minor unit for the currency, rounding half away from zero. For example:

• 42.00 USD is sent as 4200.
• 8900 JPY is sent as 8900.
• 1.234 KWD is sent as 1234.

If the currency code is missing or isn’t a valid ISO 4217 currency, mParticle doesn’t send amount or currency but still forwards the event and its products.

Custom flags

Custom flags let you set OpenAI-specific values on individual events. A custom flag takes precedence over the matching custom mapping parameter.

Custom flag	OpenAI field	Required	Description
OpenAI.SourceUrl	source_url	Conditional	The page URL where the conversion occurred. Must be an absolute http or https URL. Required for events with an action source of web, unless you provide the URL with the Source URL custom mapping parameter instead. Without a source URL, mParticle doesn’t forward web events. See Source URL.
OpenAI.Oppref	oppref	No	The OpenAI attribution identifier, forwarded without modification.
OpenAI.Obref	user.obref	No	The browser reference that the OpenAI pixel stores in the __obref cookie. Set this flag to the cookie’s value. mParticle forwards it as-is, so don’t hash it. Only set this flag for users who have given consent.
OpenAI.EventId	id	No	Overrides the event ID that OpenAI uses for deduplication. If you don’t set it, mParticle uses the event’s own ID. See Deduplication.

Source URL

OpenAI requires source_url for every event with an action source of web. mParticle uses the first valid absolute http or https URL from:

1. The OpenAI.SourceUrl custom flag.
2. The Source URL custom mapping parameter.
3. The page URL on the event, if one is set.

If the action source is web and none of these provide a valid URL, mParticle doesn’t forward the event and reports it as unable to forward.

Consent

Use the User Data Consent Mapping connection setting to select one mParticle consent purpose that controls OpenAI’s opt_out flag on each event. For more information on consent in mParticle, see Data Privacy Controls.

Consent state for the mapped purpose	opt_out value
GDPR purpose not consented	true
CCPA data sale opt-out consented (the user opted out)	true
GDPR purpose consented, or CCPA data sale opt-out not consented	false
No consent state for the purpose, or no purpose mapped	Not sent

Setting opt_out to true opts the event out of future user-level personalization in OpenAI. OpenAI doesn’t currently use Conversions API data for user-level personalization.

Enrich with IP Address

When Enrich with IP Address and Forward Device Info are both enabled, mParticle fills in a missing IP address with the user’s most recently seen IP address.

Deduplication

OpenAI deduplicates events that share the same Pixel ID, event type, and id, and keeps the first event it receives. mParticle sets id to the first available value from:

1. The OpenAI.EventId custom flag.
2. The source message ID of the event.
3. The mParticle event ID.

The same ID is reused when mParticle retries a request. If you also send the same conversions from the OpenAI pixel, set OpenAI.EventId to the pixel event’s event_id, and send both events to the same Pixel ID with the same event type. For custom events, also use the same custom event name on both sides.

Data processing notes

• Event age: OpenAI only accepts events with a timestamp within the last 7 days, and no more than 10 minutes in the future. To allow for queueing and retries, mParticle doesn’t forward events older than 7 days minus 1 hour, or more than 9 minutes in the future. These events are reported as unable to forward. This affects replays and late-arriving data.
• Validation before sending: OpenAI rejects an entire request if any event in it is invalid. To prevent one bad event from failing others, mParticle validates each event before sending it and doesn’t forward events that fail validation (for example, a web event without a source URL, or a custom event without a valid custom event name).
• Delivery: Events are forwarded server-to-server in near real time, in requests of up to 1,000 events.

• PII hashing: mParticle normalizes and hashes identities with SHA-256 before forwarding them. Values that are already SHA-256 hashes are sent as-is.

  • Email: trimmed and lowercased.
  • Phone number: spaces, parentheses, periods, hyphens, and the leading + and zeros are removed, keeping the country calling code. Only results of 8 to 15 digits are sent. mParticle doesn’t add a country calling code, so phone numbers must include one to match in OpenAI.
  • External ID (including MPID): trimmed. Case is preserved.
  • First and last name: lowercased, with all whitespace and ASCII punctuation removed.
• User attributes: country must be a two-letter ISO 3166-1 code, city must be 128 characters or fewer, and postal code must be up to 32 letters, numbers, spaces, or hyphens. Values in other formats aren’t sent.
• IP address: only valid IPv4 or IPv6 addresses are sent.
• Validate Only: while Validate Only is enabled, OpenAI validates events but doesn’t save them. Events sent during this time won’t count as conversions.

Configuration settings

Setting Name	Data Type	Required	Default Value	Description
Pixel ID	string	Yes		The Pixel ID from the conversions tab of OpenAI Ads Manager. Sent as the pid query parameter on every request.
Conversion Key	string	Yes		The conversion key you generate from the key icon in the top-right corner of OpenAI Ads Manager. Sent as a bearer token on every request. This value is stored encrypted.

Connection settings

Setting Name	Data Type	Required	Default Value	Platform	Description
Action Source	enum	Yes	Web	All	Where conversions on this connection occur. One of Web, Mobile App, Offline, Physical Store, Phone Call, Email, or Other. If you select Web, every event must include a source URL. app_installed and app_opened events always use Mobile App.
Forward Location Attributes	boolean	No	False	All	If enabled, mParticle forwards the $Country, $City, and $Zip user attributes for conversion matching. First name, last name, and phone number are sent regardless of this setting.
Forward Device Info	boolean	No	False	All	If enabled, mParticle forwards the IP address and user agent for conversion matching. Must be enabled to use Enrich with IP Address.
Enrich with IP Address	boolean	No	False	All	If enabled, mParticle fills in a missing IP address with the user’s most recently seen IP address. Requires Forward Device Info. See Enrich with IP Address.
Validate Only	boolean	No	False	All	If enabled, OpenAI validates events without saving them. Enable only during setup and testing.
External Identity Type	enum	No	Customer ID	All	The mParticle identity to send to OpenAI as the external ID (external_ids_sha256). One of None, Customer ID, MPID, or Other through Other 10. Select None to send no external ID. Events are still forwarded when the selected identity is missing.
User Data Consent Mapping	Custom mapping	No		All	The mParticle consent purpose used to set the event-level opt_out flag. Only one purpose can be selected.
Send Custom Event Attributes	boolean	No	True	All	Sends all custom event attributes to OpenAI as custom fields. Disable to send standard event data only. Use platform or feed filters to exclude specific attributes.