LiveRamp’s Online Conversions API connectors allow you to send web events with identity envelopes to various platforms using a single endpoint. Rather than setting up different implementations for each platform, this approach enables you to send standardized events to our CAPI adapter, which will then be distributed to platforms of your choice.

This program supports sending online web events to the following platforms:

Meta
Pinterest
Snapchat
TikTok
Amazon
🚧
The Amazon Online Conversions API connector is currently in closed beta. If you're interested in being considered to participate, contact your LiveRamp representative.
The Trade Desk
🚧
The Trade Desk Online Conversions API connector is currently in closed beta. If you're interested in being considered to participate, contact your LiveRamp representative.

📘
LiveRamp is continuously expanding their partnership with other platforms to support the Online Conversions API Program. Check the Changelog page periodically to stay updated when a new CAPI platform becomes available.

LiveRamp also supports sending offline events through our Offline Conversions API Programs. To learn more about the supported platforms and how to implement them, see “Conversions API Program”.

How it Works

You implement a single API payload that consolidates multiple CAPI requests on your website. When an event is triggered on your site, the conversion data will be sent to LiveRamp’s CAPI adapter. The adapter will then translate the call into requests for each platform enabled for your ATS configuration. The conversion data will then be delivered to those platforms.

View the Universal Events and Parameters

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

To view the list of supported event types, required and recommended parameters, and the supported platforms, see "Universal Events and Parameters for Online Conversions API Programs".

💡
The Universal Events and Parameters tables are dynamic and will be expanded as LiveRamp works with more platforms. Stay up-to-date by regularly checking the "Changelog" page to be notified when a new platform is supported.

Requirements

To start implementing LiveRamp’s Online Conversion API Program, you must have completed the following:

Obtained ATS configuration ID: Creating a call to the CAPI endpoint requires an ATS configuration ID. To retrieve this ID, log in to Console and select ATS → Web. Select a configuration, and select the Admin tab. You can find the Configuration ID in the "Placement Details" area.
Follow the platform-specific requirements: You need to provide additional information from each platform to give ATS access and authenticate requests. Additionally, to send events to Meta, you must have Meta-scoped envelopes enabled for you. To learn more, see “Platform-Specific Requirements for Online CAPI ”.

Overview of Steps Involved

Integrate your ATS configuration with the Online CAPI
Store the Meta-scoped envelopes (for Meta CAPI only)
Construct the payload
Create the request
Refresh the envelopes

Integrate your ATS Configuration with Online CAPI

Before sending events to our conversions API connector, you must first integrate an ATS configuration with the Conversions API in the CAPI Hub. During this process, you will have to provide account IDs, authentication tokens, or other platform-specific IDs from the platforms you want to send events to.

To integrate your ATS configuration, follow the steps under the "Create an Online Conversions API Integration" section.

Store the Meta-Scoped Envelopes

⚠️
This step is only applicable if you are sending events to Meta.

Storing Meta-scoped envelopes works the same way as storing regular ATS envelopes. When calling the ATS Envelope API with Facebook scoping applied, the response will look like the following:

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Alkc6LgKZzbqHvexyq4hyzxp0zQZnIztut2rFKjmcDtSBbM0rttk5pH2qb8iNkyxCO9kYAKg6oM2rt28dbWV6-lt9BxwoPCabDaOUXN3fr2C1qsCeV9H0qcW3wBPbbnTpxFWI0Wnh7WVPFYrCM8FgziDEBwSoYnUMO9wheayikvFSGX3Qsz1lr0QWnj2dHEMhx5V2QEbhkJ2iwH2zLEaKAt5oVa8EwAf59mOQepN3S_CwQk4C5OkgfZYiUXTYwxpDA","err":null},{"type":24,"source":"envelopeSource200","value":"BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk","err":null}]}

To store the Meta-scoped envelope:

Take the entire value of envelopeSource200 object:

BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk

Modify the result so it contains the envelope object:

{"envelope":"BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk"}

Encode the entire string to Base64 format:

eyJlbnZlbG9wZSI6IkJlRVFfYzdET0tldThYVklSSW1URVBCX3FnSGFwYk1oT29femZWa2h0Sm1EMDhvbUpzZm5IT21BU19USzkwSjFrNjJocHdFbEpyRElra1ZmQzdsSGdVbWF1eml6Umg1cUFQUmU4SUJLQWVNVzBUVzJSUkZqeFdrIn0=

Take the Base64-encoded value of envelopeSource200 and store it (with a timestamp) in a first-party cookie or local storage called _lr_fb_env.

In a first-party cookie:

function setCookieForRampIDEnvelope(envelopeSource200) {   
   document.cookie = '_lr_fb_env=' + encodeURIComponent(envelopeSource200);
}

In local storage:

function setLocalStorageForRampIDEnvelope(envelopeSource200) {   
   localStorage.setItem('_lr_fb_env' , envelopeSource200);
}

Construct the Payload and Create the Request

Construct a payload based on the events and parameters available in the Universal Events and Parameters tables. Note that some event types, such as Purchase event, require you to send additional event data.

📘
We recommend sending multiple custom data parameters to improve accuracy.

📘
Make sure to construct your payload using the keys listed under the Universal Key column in the Universal Events and Parameters table.

Include the Required Parameters

The following parameters are required for all web events:

event_name
event_id
event_time
event_source_url
event_source

To enrich your events and improve matching across the funnel, we recommend including as many of the following parameters as possible:

user_agent
ip_address
envelope
fb_envelope (Meta only)
fb_click and fb_view (Meta only)
pin_click (Pinterest only)
sc_clickand sc_view (Snapchat only)
tt_click and tt_view (TikTok only)

See the FAQ's section below to learn more about the recommendations.

Create the Request

To send the event, call the endpoint below.

POST: https://api-ingest-console.liveramp.com/ingest/<ats_config_id>

⚠️
Batch Size Limit
When sending batch events, note that this endpoint supports a maximum of 500 events per request.

Payload Examples

See some payload examples of the most common use cases below.

{
  "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"]
          }
        ]
      }

{
  "events": [
    {
      "event_id": "evt_67889",
      "event_name": "PageView",
      "event_source": "Web",
      "event_source_url": "https://example.com/subscribe/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": {
        "limited_data_use": false
      }
    }
  ]
}

{
  "events": [
    {
      "event_id": "evt_67890",
      "event_name": "Subscribe",
      "event_source": "Web",
      "event_source_url": "https://example.com/subscribe/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": {
        "subscription_id": ["sub_2025_premium"],
        "content_name": ["Monthly Premium Plan"],
        "content_type": ["subscription"],
        "content_category": ["Membership"],
        "email": ["hash256_email"],
        "first_name": ["hash256_firstname"],
        "last_name": ["hash256_lastname"],
        "zip_code": ["hash256_zipcode"],
        "country": ["hash256_country"],
        "state": ["hash256_region"],
        "city": ["hash256_city"],
        "date_of_birth": ["hash256_dob"],
        "gender": ["hash256_gender"],
        "phone": ["hash256_phone"],
        "limited_data_use": false
      }
    }
  ]
}

{
  "events": [
    {
      "event_id": "evt_67891",
      "event_name": "CompleteRegistration",
      "event_source": "Web",
      "event_source_url": "https://example.com/signup/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": {
        "email": ["hash256_email"],
        "first_name": ["hash256_firstname"],
        "last_name": ["hash256_lastname"],
        "phone": ["hash256_phone"],
        "date_of_birth": ["hash256_dob"],
        "gender": ["hash256_gender"],
        "zip_code": ["hash256_zipcode"],
        "country": ["hash256_country"],
        "state": ["hash256_region"],
        "city": ["hash256_city"],
        "lead_id": ["hash256_lead_id"],
        "limited_data_use": false
      }
    }
  ]
}

{
  "events": [
    {
      "event_id": "evt_67892",
      "event_name": "Search",
      "event_source": "Web",
      "event_source_url": "https://example.com/search?q=running+shoes",
      "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": {
        "search_string": ["running shoes"],
        "content_category": ["Footwear"],
        "limited_data_use": false
      }
    }
  ]
}

{
  "events": [
    {
      "event_id": "evt_67893",
      "event_name": "ViewContent",
      "event_source": "Web",
      "event_source_url": "https://example.com/products/item_123",
      "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"],
        "content_name": ["Example Shoe"],
        "content_type": ["product"],
        "content_category": ["Footwear"],
        "content_brand": ["ExampleBrand"],
        "currency": ["USD"],
        "value": ["55.00"],
        "num_items": ["1"],
        "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"]
          }
        ]
      }
    }
  ]
}

{
  "events": [
    {
      "event_id": "evt_67894",
      "event_name": "AddToWishlist",
      "event_source": "Web",
      "event_source_url": "https://example.com/products/item_123",
      "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"],
        "content_name": ["Example Shoe"],
        "content_type": ["product"],
        "content_category": ["Footwear"],
        "content_brand": ["ExampleBrand"],
        "currency": ["USD"],
        "value": ["55.00"],
        "num_items": ["1"],
        "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"]
          }
        ]
      }
    }
  ]
}

{
  "events": [
    {
      "event_id": "evt_67895",
      "event_name": "AddToCart",
      "event_source": "Web",
      "event_source_url": "https://example.com/cart",
      "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"],
        "content_name": ["Example Shoe"],
        "content_type": ["product"],
        "content_category": ["Footwear"],
        "content_brand": ["ExampleBrand"],
        "currency": ["USD"],
        "value": ["55.00"],
        "num_items": ["2"],
        "limited_data_use": false,
        "contents": [
          {
            "item_id": ["item_123"],
            "item_price": ["55.00"],
            "item_quantity": ["2"],
            "item_name": ["Example Shoe"],
            "item_brand": ["ExampleBrand"],
            "item_category": ["Footwear"]
          }
        ]
      }
    }
  ]
}

{
  "events": [
    {
      "event_id": "evt_67896",
      "event_name": "InitiateCheckout",
      "event_source": "Web",
      "event_source_url": "https://example.com/checkout",
      "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"],
        "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"]
          }
        ]
      }
    }

Refresh the ATS Envelopes

You can refresh existing CAPI-scoped envelopes by calling:

https://api.rlcdn.com/api/identity/v2/envelope/refresh?pid=[placement id]&it=[envelope type]&iv=[envelope value]&ct=[consent type]&cv=[consent string]

You must populate the it parameter with 19 to correspond to the CAPI-scoped envelope type. This will reset the envelope expiration to the maximum allowed value.

To learn more about refreshing envelopes, see Implement the ATS Envelope Refresh API.

FAQ's

What is the benefit of including additional identifiers such as platform cookies, IP address and others?

When using a CAPI platform’s HTML tag on your site (for example, Meta Pixel, Pinterest Tag, and TikTok Pixel), the platform may drop first-party cookies that store click or view IDs specific to that platform. These values, such as _fbp and _fbc, can be captured and included in the user_data payload to help improve match rates and signal quality.

However, platform cookies are just one part of the broader identity strategy.

To fully enrich your events and support user matching across the funnel, we recommend also including:

user_agent and ip_address
Hashed PII: email, phone, first name, last name, city, state, zip, and country.
Platform-specific cookies when available. For example, _fbp, _fbc, _epik, _scid, ttclid, and_ttp.
Envelopes when available

Why are additional identifiers important for upper-funnel events?

Purchase events often contain a clear identifier, like an email address, that enables user matching and RampID generation. However, upper-funnel events, such as Page View, View Content, or Search, often lack persistent identifiers, especially if the user hasn’t logged in or shared their information yet.

In those cases, adding fallback identifiers such as platform cookies, IP address, and user agent can make a major difference in making those events eligible for attribution and optimization.

What Is the Event Match Quality Score?

Event Match Quality Score is a diagnostic metric shown in many platforms’ event managers. It reflects the completeness and richness of the user identifiers present in each event. It does not measure how often a RampID or PII matches the platform’s user base, it only evaluates the strength of the signal being sent.

A higher score typically means:

Stronger signal integrity
Better attribution outcomes
Improved optimization performance

The Online Conversions API Connectors for API Implementation

🚧

🚧

📘

How it Works

View the Universal Events and Parameters

💡

Requirements

Overview of Steps Involved

Integrate your ATS Configuration with Online CAPI

Store the Meta-Scoped Envelopes

⚠️

Construct the Payload and Create the Request

📘

📘

Include the Required Parameters

Create the Request

⚠️
Batch Size Limit

Payload Examples

Refresh the ATS Envelopes

FAQ's

What is the benefit of including additional identifiers such as platform cookies, IP address and others?

Why are additional identifiers important for upper-funnel events?

What Is the Event Match Quality Score?

🚧

🚧

📘

How it Works

View the Universal Events and Parameters

💡

Requirements

Overview of Steps Involved

Integrate your ATS Configuration with Online CAPI

Store the Meta-Scoped Envelopes

⚠️

Construct the Payload and Create the Request

📘

📘

Include the Required Parameters

Create the Request

⚠️Batch Size Limit

Payload Examples

Refresh the ATS Envelopes

FAQ's

What is the benefit of including additional identifiers such as platform cookies, IP address and others?

Why are additional identifiers important for upper-funnel events?

What Is the Event Match Quality Score?

⚠️
Batch Size Limit