Universal Events and Parameters for Online Conversions API Program

LiveRamp’s Online Conversion API program utilizes unified schema parameters with a mapping system that translates our parameters to each platform’s specific parameters.

This article lists the following:

Universal event types and the platforms that support them
Parameters required for API implementations
User data keys for API implementations
Platform-specific provider data for API implementations
Custom data parameters and the platforms that support them
Contents parameters and the platforms that support them

For API users, make sure to construct your payload using the keys listed under the Universal Key column. For ATS for Web implementations, you can configure these events and parameters when you create the event in Console.

For instructions on implementing the Online Conversions API for ATS for Web, see "Implement Online CAPI"

For instructions on implementing the Online Conversions API with ATS API calls, see "Online Conversions API Program for API Implementation".

Note

The tables in this article will continue to expand as LiveRamp works with additional platforms. Stay up-to-date by regularly checking the "Release Notes and System Information" page to be notified when a new platform is supported.

Tip

If an event or parameter is not supported by one of your enabled CAPI platforms, the event data will still be sent to other platforms that do support it.

For example, you've enabled Meta, Pinterest, Snapchat, and TikTok in your CAPI integration. You then create an Add Payment Info event, which is only supported by Meta and TikTok. When the specified event takes place, the conversion data will be sent to Meta and TikTok only.

Event Types

The following events are available to send to the platforms that support them.

Universal Event Name	Universal Key	Description
Ad Click Event	AdClick	A user clicks an ad.
Ad View Event	AdView	A user views an ad.
Add Billing Event	AddBilling	A user configures their payment information.
Add Payment Info Event	AddPaymentInfo	A user adds their payment information at checkout.
Add To Cart Event	AddToCart	A user adds a product to the shopping cart.
Add To Wishlist Event	AddToWishlist	A user adds a product the wishlist.
Application Approval Event	ApplicationApproval	An application submitted by a user is approved.
Complete Registration Event	CompleteRegistration	A user signs up or creates an account by completing a registration form.
Contact Event	Contact	A user contacts your business via chat, email, telephone, etc,
Customize Product Event	CustomizeProduct	A user customizes a product.
Donate Event	Donate	A user donates to your organization or a cause.
Download Event	Download	A user downloads something from your websites.
Find Location Event	FindLocation	A user searches for a location on your website, such as looking for the location of a physical store.
Initiate Checkout Event	InitiateCheckout	A user starts the checkout flow to purchase items.
Invite Event	Invite	A user invites another user.
Lead Event	Lead	A user completes a form (sign up) to get more information.
Level Complete Event	LevelComplete	A user completes a level.
List View Event	ListView	A user views a list.
Page View Event	PageView	When a user visits a product or article page.
Purchase Event Required parameters: `currency`, `value`	Purchase	A user completes the checkout flow or a purchase.
Rate Event	Rate	A user rates a product or a service.
Reserve Event	Reserve	A user makes a reservation.
Save Event	Save	A user saves content, product, or offer to revisit later.
Schedule Event	Schedule	A user schedules an appointment to visit your business.
Search Event	Search	A user searches or uses the search bar.
Share Event	Share	A user shares content such as posts, products, or promotions.
Start Trial Event	StartTrial	A user begins a free trial to use a product or service your business offers
Submit Application Event	SubmitApplication	A user applies for something that your business offers.
Submit Form Event	SubmitForm	A user submits a form or application.
Subscribe Event	Subscribe	A user subscribes to content on your website, including paid subscription.
View Category Event	ViewCategory	A user views a product category page.
View Content Event	ViewContent	A user visits a specific page related to your business, such as a product page or landing page.
Watch Video Event	WatchVideo	A user watches a video.

Required Parameters

For API implementations, you are required to include all the parameters in the following table in your request payload. For ATS for Web implementations, you provide the data when you create the event in Console.

Parameter Name	Universal Key	Description
Event Name string	event_name	The event name from the list all universal event types.
Event ID string	event_id	A unique string that identifies the event and can be used for deduplication between events.
Event Time integer	event_time	The time when the event happened in Unix timestamp.
Event Source URL string	event_source_url	The browser URL when the event happened.
Event Source string	event_source	Where the event occurred. Currently can only be set to `Web`.

User Data Keys

For API implementations, we recommend always adding the following identifier data to enrich your events and improve match rates. Especially with upper-funnel events such as Page View, View Content, or Search, which often lack identifiers.

User Data	Universal Key	Description
Envelope Data string	envelope	Identity envelope value.
Facebook Envelope Data string	fb_envelope	Facebook-scoped envelope value.
Client User Agent string	user_agent	The user agent from the user's device where the event occurred. Caution If the user_agent parameter is not present in your API payload, the adapter retrieve user agent from the request header.
Client IP Address string	ip_address	The IP address of the user's device. Caution If the ip_address parameter is not present in your API payload, the adapter will automatically retrieve IP address from the request header.

Provider Data

For API implementations, we recommend including the following platform-specific parameters in your payload.

Platform	Provider Data	Universal Key	Description
Meta	Facebook Click ID	fb_click	The Facebook click ID value stored in the `_fbc` browser cookie under your domain. Can also be found in the `fbclid=` URL query parameter, but requires special formatting. See Meta's article "Managing fbc and fbp Parameters" for more info.
Meta	Facebook View ID	fb_view	The Facebook browser ID value stored in the `_fbp` browser cookie under your domain. See Meta's article "Managing fbc and fbp Parameters" for more info.
Pinterest	Pinterest Click ID	pin_click	The `_epik` cookie value that is generated when a user clicks an ad. The value can also be found in the `epik=` URL query parameter.
Snapchat	Snapchat Click ID	sc_click	The ID value stored in the landing page URL’s `&ScCid=` query parameter.
Snapchat	Snapchat View ID	sc_view	The 1st party cookie if you are using the Pixel SDK, which can be accessed by looking at the `_scid` value under your domain.
TikTok	TikTok Click ID	tt_click	TikTok Click ID, a data connection parameter appended to a landing page URL whenever a user clicks on an ad on TikTok. The value can be found in the `ttclid` cookie or the `ttclid=` URL parameter.
TikTok	TikTok View ID	tt_view	Cookie ID. If you also use Pixel SDK and have enabled cookies, Pixel SDK automatically saves a unique identifier in the `_ttp` cookie.

Custom Data

Parameters marked as "Recommended" mean that including them will help create more accurate and higher quality conversion data. Parameters marked as "Optional" mean that including them can provide more context in your conversion data.

We highly suggest including as many recommended parameters as possible when you set up your event in Console or when you are constructing you request payload.

For API implementations, you can pass the following data as part of the custom_data object. For ATS for Web implementations, you can include the parameters by enabling "Add Custom Data Parameters" in your event's setting.

Universal Parameter Name	Universal Key	Description	Reccomendation
Content IDs array of string	content_ids	The product IDs (or SKUs) associated with the event.	Optional
Content Category array of string	content_category	The category of the product.	Optional
Content Name array of string	content_name	The name of the product.	Optional
Content Type array of string	content_type	Used to indicate what the keys the content IDs represent; individual items or multiple items in group.	Optional
Currency array of string	currency	ISO 4217 code of the currency associated with the value.	Required for Purchase events
Email array of string	hashed_email	The user's SHA256-hashed email address.	Recommended
Number of Items array of string	num_items	The number of items the user has during checkout.	Optional
Order ID array of string	order_id	A string of ID for this specific transaction.	Optional
Description array of string	description	A string description of the product.	Optional
Phone Number array of string	hashed_phone	The user's SHA256-hashed phone number.	Recommended
Predicted LTV array of string (stringified float)	predicted_ltv	The predicted lifetime value of a conversion event.	Optional
Search String array of string	search_string	The text that was used for the search event.	Optional
Value array of string (stringified float)	value	Total value of items with item_price attribute within the "contents" object (i.e. basket-level value).	Required for Purchase events
Content Brand array of string	content_brand	The brand associated with the content ID.	Optional
Event Tag array of string	event_tag	Custom event set label.	Optional
Shop ID array of string	shop_id	The shop ID.	Optional
First Name array of string	first_name	The user's SHA256-hashed first name.	Recommended
Last Name array of string	last_name	The user's SHA256-hashed last name.	Recommended
Zip Code array of string	zip_code	The user's SHA256-hashed zip code.	Recommended
Date of Birth array of string	date_of_birth	The user's SHA256-hashed date of birth.	Recommended
Gender array of string	gender	The user's SHA256-hashed gender.	Recommended
City array of string	city	The SHA256-hashed city associated with the event.	Recommended
Country array of string	country	The SHA256-hashed country associated with the event.	Recommended
State array of string	state	The SHA256-hashed state associated with the event.	Recommended
Facebook Login ID array of string	fb_login_id	The ID issued by Meta when a person first logs into an instance of an app. This is also known as App-Scoped ID.	Optional
Lead ID array of string	lead_id	The ID associated with a lead.	Optional
Subscription ID array of string	subscription_id	The subscription ID of the user in the event.	Optional
Limited Data Use boolean	limited_data_use	Data processing options to enable for specific events. You can set this parameter to help comply with various US state privacy regulations.	Optional

Content Properties

Include the optional parameters in the following table to provide more context on every individual item in an event.

For API implementations, you can pass the following data as part of the contents object. For ATS for Web implementations, you can include the parameters by enabling "Add Contents" in your event setting.

Content Property	Universal Key	Description
Item ID array of string	item_id	Unique ID of the individual item.
Item Price array of string (stringified float)	item_price	Price of the individual item.
Item Quantity array of string (stringified integer)	item_quantity	Quantity of the individual item.
Item Name array of string	item_name	Name of the individual item or page.
Item Brand array of string	item_brand	Brand of the individual item.
Item Category array of string	item_category	Product category of an individual item.

In this section: