--- updatedAt: 2026-08-25T12:13:04.000Z agentTools: siteIndex: https://developers.liveramp.com/llms.txt projectIndex: https://developers.liveramp.com/authenticatedtraffic-api/llms.txt --- # Send online conversion events (web) Submit one or more web conversion events associated with an ATS configuration. Events are validated and routed to each enabled CAPI platform that supports the given event type. **Timing rules** * Do not send conversions that occurred more than 7 days ago. * Do not send conversions with a conversion date in the future. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "LiveRamp Online Conversions API (CAPI) - Web Events", "description": "Endpoint for sending online conversion events for **web** sources to LiveRamp's Online Conversions API program. LiveRamp translates these unified schema parameters into each supported ad platform's own event format (Amazon, Meta, Pinterest, Snapchat, TikTok, The Trade Desk, Yahoo).\n\nField names in this spec use the **Universal Key** values documented in [Universal Events and Parameters for Online Conversions API Program](https://docs.liveramp.com/privacy-manager/en/universal-events-and-parameters-for-online-conversions-api.html).\n\nFor app events, see the companion spec: `online-capi-openapi-app.yaml`.\n", "version": "1.0.0" }, "servers": [ { "url": "https://api-ingest-console.liveramp.com" } ], "paths": { "/ingest/{ats_config_id}": { "post": { "summary": "Send online conversion events (web)", "description": "Submit one or more web conversion events associated with an ATS configuration. Events are validated and routed to each enabled CAPI platform that supports the given event type.\n\n**Timing rules** * Do not send conversions that occurred more than 7 days ago. * Do not send conversions with a conversion date in the future.\n", "operationId": "sendOnlineConversionEventsWeb", "tags": [ "Online Conversions API - Web" ], "parameters": [ { "name": "ats_config_id", "in": "path", "required": true, "description": "The unique identifier of the ATS configuration that this event batch is associated with.", "schema": { "type": "string" }, "example": "8f3a1c2d-4b5e-4a11-9c77-example12345" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/conversion_event_batch" }, "example": { "events": [ { "event_id": "evt_67897", "event_name": "Purchase", "event_source": "Web", "event_source_url": "https://example.com/confirmation", "event_time": 1752505804, "user_data": { "envelope": "id_env", "fb_envelope": "id_fb_envelope", "ip_address": "192.0.2.100", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" }, "provider_data": { "fb_click": "id_fb_click", "fb_view": "id_fb_view", "pin_click": "id_pin_click", "sc_click": "id_sc_click", "sc_view": "id_sc_view", "tt_click": "id_tt_click", "tt_view": "id_tt_view" }, "custom_data": { "content_ids": [ "item_123", "item_456" ], "content_name": [ "Example Shoe", "Example Hoodie" ], "content_type": [ "product" ], "content_category": [ "Apparel" ], "content_brand": [ "ExampleBrand" ], "order_id": [ "order_789" ], "currency": [ "USD" ], "value": [ "105.00" ], "num_items": [ "2" ], "limited_data_use": false, "contents": [ { "item_id": [ "item_123" ], "item_price": [ "55.00" ], "item_quantity": [ "1" ], "item_name": [ "Example Shoe" ], "item_brand": [ "ExampleBrand" ], "item_category": [ "Footwear" ] }, { "item_id": [ "item_456" ], "item_price": [ "50.00" ], "item_quantity": [ "1" ], "item_name": [ "Example Hoodie" ], "item_brand": [ "ExampleBrand" ], "item_category": [ "Clothing" ] } ] } } ] } } } }, "responses": { "200": { "description": "Event call processed. The response includes a REQUEST_ID that can be used to look up this specific event call for debugging purposes.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ingest_response" }, "example": { "REQUEST_ID": [ "cc07bb43-8f5e-43c0-970f-2a6b7b81d4c2" ], "providers": { "data": {} } } } } } } } } }, "components": { "schemas": { "conversion_event_batch": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "description": "One or more web conversion events to send in this request.", "items": { "$ref": "#/components/schemas/event" } } } }, "event": { "type": "object", "description": "A single web conversion event.", "required": [ "event_id", "event_name", "event_source", "event_source_url", "event_time" ], "properties": { "event_id": { "type": "string", "description": "A unique string that identifies the event and can be used for deduplication between events.", "example": "evt_67897" }, "event_name": { "type": "string", "description": "The event type key. Must be one of the universal event types that support web as an event source. Each event is only sent to the ad platforms that support it (see table below).\n\n| Event | Supported Platforms |\n| --- | --- |\n| AddBilling | Snapchat, Yahoo |\n| AddPaymentInfo | Meta, Pinterest, TikTok, Yahoo |\n| AddToCart | Amazon, Meta, OpenAI, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo |\n| AddToWishlist | Meta, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo |\n| AdClick | Snapchat, Yahoo |\n| AdView | Snapchat, Yahoo |\n| ApplicationApproval | TikTok, Yahoo |\n| CompleteRegistration | Amazon, Meta, Pinterest, Reddit, Snapchat, TikTok, Yahoo |\n| Contact | Amazon, Meta, TikTok, The Trade Desk, Yahoo |\n| ConvertedLead | Yahoo |\n| CustomizeProduct | Meta, TikTok, Yahoo |\n| Donate | Meta, Yahoo |\n| Engagement | Yahoo |\n| FindLocation | Meta, TikTok, The Trade Desk, Yahoo |\n| ImportedLead | Yahoo |\n| InitiateCheckout | Amazon, Meta, OpenAI, Pinterest, Snapchat, TikTok, The Trade Desk, Yahoo |\n| Invite | Snapchat, Yahoo |\n| Lead | Meta, OpenAI, Pinterest, Amazon, Reddit, Yahoo |\n| LevelComplete | Snapchat, Yahoo |\n| ListView | Snapchat, Yahoo |\n| OutboundClick | Yahoo |\n| PageView | Amazon, Meta, OpenAI, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo |\n| Purchase | Amazon, Meta, OpenAI, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo |\n| QualifiedLead | Yahoo |\n| Rate | Snapchat, Yahoo |\n| RequestQuote | Yahoo |\n| Reserve | Snapchat, Yahoo |\n| Save | Snapchat, Yahoo |\n| Schedule | Meta, OpenAI, TikTok, Yahoo |\n| Search | Amazon, Meta, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo |\n| SearchCategory | The Trade Desk, Yahoo |\n| Share | Snapchat, Yahoo |\n| StartTrial | Meta, OpenAI, Snapchat, TikTok, Yahoo |\n| StoreSale | Yahoo |\n| StoreVisit | Yahoo |\n| SubmitApplication | Meta, TikTok, Amazon, Yahoo |\n| SubmitForm | TikTok, Yahoo |\n| Subscribe | Amazon, Meta, OpenAI, Pinterest, Snapchat, TikTok, Yahoo |\n| ViewCart | The Trade Desk, Yahoo |\n| ViewCategory | Pinterest, Yahoo |\n| ViewContent | Meta, OpenAI, Pinterest, Snapchat, TikTok, The Trade Desk, Yahoo |\n| WatchVideo | Pinterest, Yahoo |", "enum": [ "AddBilling", "AddPaymentInfo", "AddToCart", "AddToWishlist", "AdClick", "AdView", "ApplicationApproval", "CompleteRegistration", "Contact", "ConvertedLead", "CustomizeProduct", "Donate", "Engagement", "FindLocation", "ImportedLead", "InitiateCheckout", "Invite", "Lead", "LevelComplete", "ListView", "OutboundClick", "PageView", "Purchase", "QualifiedLead", "Rate", "RequestQuote", "Reserve", "Save", "Schedule", "Search", "SearchCategory", "Share", "StartTrial", "StoreSale", "StoreVisit", "SubmitApplication", "SubmitForm", "Subscribe", "ViewCart", "ViewCategory", "ViewContent", "WatchVideo" ], "example": "Purchase" }, "event_source": { "type": "string", "description": "Where the event occurred.", "enum": [ "web" ], "example": "Web" }, "event_source_url": { "type": "string", "format": "uri", "description": "The browser URL when the event happened.", "example": "https://example.com/confirmation" }, "event_time": { "type": "integer", "format": "int64", "description": "The date/time of the event as a Unix timestamp in seconds. Must not be in the future. Must not be more than 7 days ago.\n", "example": 1752505804 }, "user_data": { "$ref": "#/components/schemas/user_data" }, "provider_data": { "$ref": "#/components/schemas/provider_data" }, "custom_data": { "$ref": "#/components/schemas/custom_data" } } }, "user_data": { "type": "object", "description": "Identifier data used to enrich events and improve match rates. Recommended for all events, especially upper-funnel events (e.g. PageView, ViewContent, Search) that often lack identifiers.\n", "properties": { "envelope": { "type": "string", "description": "Identity envelope value. If pulled from storage, the value must be Base64-decoded before sending." }, "fb_envelope": { "type": "string", "description": "Facebook-scoped envelope value. If pulled from storage, the value must be Base64-decoded before sending." }, "user_agent": { "type": "string", "description": "The user agent from the user's device where the event occurred. If not present in the payload, the adapter will retrieve it from the request header.\n" }, "ip_address": { "type": "string", "description": "The IP address of the user's device. If not present in the payload, the adapter will retrieve it from the request header.\n" } } }, "provider_data": { "type": "object", "description": "Platform-specific click/view identifiers for web events, so platforms can tie a conversion back to the exact ad click or view that generated it.\n", "properties": { "fb_click": { "type": "string", "description": "Facebook Click ID, stored in the `_fbc` browser cookie or the `fbclid=` URL query parameter.\n\n**Supported platforms:** Meta" }, "fb_view": { "type": "string", "description": "Facebook View ID (browser ID), stored in the `_fbp` browser cookie.\n\n**Supported platforms:** Meta" }, "pin_click": { "type": "string", "description": "Pinterest Click ID, from the `_epik` cookie or `epik=` URL query parameter.\n\n**Supported platforms:** Pinterest" }, "sc_click": { "type": "string", "description": "Snapchat Click ID, from the landing page URL's `&ScCid=` query parameter.\n\n**Supported platforms:** Snapchat" }, "sc_view": { "type": "string", "description": "Snapchat View ID, from the `_scid` first-party cookie (Pixel SDK).\n\n**Supported platforms:** Snapchat" }, "tt_click": { "type": "string", "description": "TikTok Click ID, from the `ttclid` cookie or `ttclid=` URL parameter.\n\n**Supported platforms:** TikTok" }, "tt_view": { "type": "string", "description": "TikTok View ID, from the `_ttp` cookie (Pixel SDK).\n\n**Supported platforms:** TikTok" }, "ttd_view": { "type": "string", "description": "The Trade Desk Impression ID, appended to the landing page URL at ad bid time.\n\n**Supported platforms:** The Trade Desk" }, "oai_view": { "type": "string", "description": "OpenAI-provided privacy-preserving identifier, found in the landing page URL's `oppref=` query parameter.\n\n**Supported platforms:** OpenAI" }, "rd_click": { "type": "string", "description": "Reddit Click ID.\n\n**Supported platforms:** Reddit" }, "rd_view": { "type": "string", "description": "Reddit View ID.\n\n**Supported platforms:** Reddit" } } }, "custom_data": { "type": "object", "description": "Additional event and transaction-level data. Recommended parameters improve conversion data accuracy; optional parameters add further context.\n\n**Note:** `currency` and `value` are required whenever `event_name` is `Purchase`.", "properties": { "content_ids": { "type": "array", "items": { "type": "string" }, "description": "The product IDs (or SKUs) associated with the event.\n\n**Supported platforms:** Meta, Pinterest, Snapchat, TikTok" }, "content_category": { "type": "array", "items": { "type": "string" }, "description": "The category of the product.\n\n**Supported platforms:** Meta, Pinterest, Snapchat" }, "content_name": { "type": "array", "items": { "type": "string" }, "description": "The name of the product.\n\n**Supported platforms:** Meta, Pinterest, Snapchat" }, "content_type": { "type": "array", "items": { "type": "string" }, "description": "Indicates what the content IDs represent (individual item vs. multiple items in a group).\n\n**Supported platforms:** Meta, Snapchat, TikTok" }, "currency": { "type": "array", "items": { "type": "string" }, "description": "ISO 4217 code of the currency associated with the value.\n\n**Required for `Purchase` events.**\n\n**Supported platforms:** Amazon, Meta, OpenAI, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo" }, "email": { "type": "array", "items": { "type": "string" }, "description": "The user's email address.\n**Required by OpenAI to allow matching.**\n**Supported platforms:** Meta, OpenAI, Reddit" }, "num_items": { "type": "array", "items": { "type": "string" }, "description": "The number of items the user has during checkout.\n\n**Supported platforms:** Amazon, Meta, Pinterest, Reddit, Snapchat, TikTok" }, "order_id": { "type": "array", "items": { "type": "string" }, "description": "A string ID for this specific transaction.\n\n**Supported platforms:** Meta, Pinterest, Snapchat, TikTok, The Trade Desk, Yahoo" }, "description": { "type": "array", "items": { "type": "string" }, "description": "A string description of the product.\n\n**Supported platforms:** TikTok" }, "phone_number": { "type": "array", "items": { "type": "string" }, "description": "The user's phone number.\n\n**Supported platforms:** Meta, Reddit" }, "predicted_ltv": { "type": "array", "items": { "type": "string" }, "description": "The predicted lifetime value of a conversion event (stringified float).\n\n**Supported platforms:** Meta, Snapchat" }, "search_string": { "type": "array", "items": { "type": "string" }, "description": "The text that was used for the search event.\n\n**Supported platforms:** Meta, Pinterest, Snapchat, TikTok" }, "value": { "type": "array", "items": { "type": "string" }, "description": "Total value of items with the item_price attribute within the contents object (basket-level value), stringified float.\n\n**Required for `Purchase` events.**\n\n**Supported platforms:** Amazon, Meta, OpenAI, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo" }, "content_brand": { "type": "array", "items": { "type": "string" }, "description": "The brand associated with the content ID.\n\n**Supported platforms:** Pinterest" }, "event_tag": { "type": "array", "items": { "type": "string" }, "description": "Custom event set label.\n\n**Supported platforms:** Snapchat" }, "shop_id": { "type": "array", "items": { "type": "string" }, "description": "The shop ID.\n\n**Supported platforms:** TikTok" }, "first_name": { "type": "array", "items": { "type": "string" }, "description": "The user's first name.\n\n**Supported platforms:** Meta" }, "last_name": { "type": "array", "items": { "type": "string" }, "description": "The user's last name.\n\n**Supported platforms:** Meta" }, "zip_code": { "type": "array", "items": { "type": "string" }, "description": "The user's zip code.\n\n**Supported platforms:** Meta, OpenAI, The Trade Desk" }, "date_of_birth": { "type": "array", "items": { "type": "string" }, "description": "The user's date of birth.\n\n**Supported platforms:** Meta" }, "gender": { "type": "array", "items": { "type": "string" }, "description": "The user's gender.\n\n**Supported platforms:** Meta, Pinterest, Snapchat" }, "city": { "type": "array", "items": { "type": "string" }, "description": "The city associated with the event.\n\n**Supported platforms:** Meta, OpenAI, Pinterest, Snapchat, TikTok, The Trade Desk" }, "country": { "type": "array", "items": { "type": "string" }, "description": "The country associated with the event.\n\n**Supported platforms:** Amazon, Meta, OpenAI, Pinterest, Snapchat, TikTok, The Trade Desk, Yahoo" }, "state": { "type": "array", "items": { "type": "string" }, "description": "The state associated with the event.\n\n**Supported platforms:** Meta, Pinterest, Snapchat, TikTok, The Trade Desk, Yahoo" }, "fb_login_id": { "type": "array", "items": { "type": "string" }, "description": "The App-Scoped ID issued by Meta when a person first logs into an instance of an app.\n\n**Supported platforms:** Meta" }, "lead_id": { "type": "array", "items": { "type": "string" }, "description": "The ID associated with a lead.\n\n**Supported platforms:** Meta, Snapchat" }, "subscription_id": { "type": "array", "items": { "type": "string" }, "description": "The subscription ID of the user in the event.\n\n**Supported platforms:** Meta, Snapchat" }, "limited_data_use": { "type": "boolean", "description": "Data processing options to enable for specific events, to help comply with various US state privacy regulations.\n\n**Supported platforms:** Amazon, Meta, OpenAI, Pinterest, Reddit, Snapchat, TikTok, Yahoo", "example": false }, "contents": { "type": "array", "description": "SKU-level detail for each individual item in the event.", "items": { "$ref": "#/components/schemas/content" } } } }, "content": { "type": "object", "description": "Detail for a single item within the \"contents\" array.", "required": [ "item_id" ], "properties": { "item_id": { "type": "array", "items": { "type": "string" }, "description": "Unique ID of the individual item. Required if contents is used.\n\n**Supported platforms:** Meta, Pinterest, OpenAI, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo" }, "item_price": { "type": "array", "items": { "type": "string" }, "description": "Price of the individual item (stringified float).\n\n**Supported platforms:** Meta, Pinterest, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo" }, "item_quantity": { "type": "array", "items": { "type": "string" }, "description": "Quantity of the individual item (stringified integer).\n\n**Supported platforms:** Meta, Pinterest, OpenAI, Reddit, Snapchat, TikTok, The Trade Desk, Yahoo" }, "item_name": { "type": "array", "items": { "type": "string" }, "description": "Name of the individual item or page.\n\n**Supported platforms:** OpenAI, Pinterest, Reddit, TikTok, The Trade Desk, Yahoo" }, "item_brand": { "type": "array", "items": { "type": "string" }, "description": "Brand of the individual item.\n\n**Supported platforms:** Meta, Pinterest, Snapchat, TikTok, Yahoo" }, "item_brand_id": { "type": "array", "items": { "type": "string" }, "description": "Brand ID of the individual item.\n\n**Supported platforms:** Pinterest" }, "item_category": { "type": "array", "items": { "type": "string" }, "description": "Product category of the individual item.\n\n**Supported platforms:** OpenAI, Pinterest, Reddit, TikTok, The Trade Desk, Yahoo" }, "item_subcategory": { "type": "array", "items": { "type": "string" }, "description": "Sub-category of the individual item.\n\n**Supported platforms:** Yahoo" } } }, "ingest_response": { "type": "object", "description": "Response returned for the event call. Contains a request ID that can be used to look up this specific call for debugging purposes.\n", "properties": { "REQUEST_ID": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Unique identifier(s) for this event call, used for debugging and support lookups.", "example": [ "cc07bb43-8f5e-43c0-970f-2a6b7b81d4c2" ] }, "providers": { "type": "object", "description": "Platform-level response data returned by each enabled CAPI provider.", "properties": { "data": { "type": "object", "description": "Per-provider response details. Structure varies by provider." } } } } } } } } ```