ECAPI specification mapping

This guide helps developers using the IAB Tech Lab Event and Conversion API (ECAPI) specification map their event and conversion data to the Data Manager API event ingestion schema.

Overview

ECAPI is a platform-agnostic, open-source data standard designed to define how marketing-related events and conversions are structured.

The following table provides a high-level view of how key attributes and design principles of ECAPI compare to the Data Manager API.

	ECAPI	Data Manager API
Deduplication	Relies on id (event ID)	Relies on transaction_id
Event routing	The destination of the data is indicated by the data_set_id field in the event payload.	The destinations field of the request defines the destination(s) for the events. Data Manager API also supports routing events to multiple destinations in a single request. See the destinations guide for more information.
Privacy and consent fields	Global Privacy Platform (GPP) consent strings	Data Manager API does not accept or parse Global Privacy Platform (GPP) consent strings. Consent fields must be set in the Consent object. You can set consent at either the request level (which applies to all events in the request) or at the event level (which lets you specify different consent settings for individual events).

Structural field mapping

The following mapping tables define how individual fields from the ECAPI specification translate into fields accepted by the Data Manager API.

Tip: Refer to the Send events guide to get started with sending events and to learn more about the required and optional fields for each event ingestion use case.

Event object mapping

ECAPI (event)	Data Manager API (Event)	Notes
data_set_id	destinations[].product_destination_id (Request level) destination_references (Event level)	Can be defined at the following levels: Request level (Required): Specify the list of destinations in the IngestEventsRequest. Event level: Use the destination_references field on the Event object. Add an entry to specify which destination from the destinations list should receive the event. For more information on how to define a Destination and determine the product destination ID, see Configure destinations and headers.
id	transaction_id	This value is used for deduplicating conversion events. Learn more.
timestamp	event_timestamp	Required. ECAPI uses the Unix epoch format (integer) for timestamps. When mapping to the Data Manager API, the event_timestamp field must be converted to one of the following formats: If using JSON format, set to a value in RFC 3339 format. If using protocol buffers, use a Timestamp and set the seconds and (optionally) the nanoseconds fields. See Timestamp format for details.
event_type / custom_event	event_name	This can be a recommended event name (for example, purchase) or a custom event name. See Standard event names for details.
user_data	user_data	Maps to the UserData object, which accepts a list of UserIdentifier objects.
value	conversion_value	Map directly as a double or float representing the monetary value of the conversion.
currency_code	currency	Map to a three-letter uppercase currency code (for example, USD).
source	event_source	Set to a value from the EventSource enum.
properties	cart_data custom_variables additional_event_parameters	Transaction-level items can be mapped to the cart_data.items array in the CartData object. The Data Manager API supports several optional Merchant Center fields for products that exist in Merchant Center accounts. If your destination is a Google Ads conversion action, you can also include additional custom parameters in the custom_variables field as a list of CustomVariable objects. If your destination is a Google Analytics data stream, you can include additional event parameters in the additional_event_parameters field as a list of AdditionalEventParameter objects.
ext	No equivalent

User data object mapping

Tip: Refer to the Convert the data to Event objects section in the Send events guide for more information on which identifiers are required and recommended for each destination and use case.

In the Data Manager API, the user_data field on the Event object accepts a UserData object. This expects a list of UserIdentifier objects, which can contain individual user identifiers such as email addresses, phone numbers, or address components.

ECAPI (user_data)	Data Manager API (Event)	Notes
customer_identifier	user_id (Google Analytics)	For Google Analytics events, the user_id field represents a User-ID. The Data Manager API does not support generic customer ID fields for other destinations.
uids	No equivalent	Data Manager API does not support a structured uids array containing agent types and domains.
customer_segments	user_properties	Map to UserProperties on the Event.
email_address	user_data.user_identifiers[].email_address	Set to the formatted and hashed email address. You can also encrypt the hashed email address.
phone_numbers	user_data.user_identifiers[].phone_number	Set to the formatted and hashed phone number. You can also encrypt the hashed phone number.
utcoffset	No equivalent	If you're using JSON format, you can specify the timezone offset directly in the RFC 3339 event_timestamp string. If you're using protocol buffers, you can use utility functions such as Timestamps.parse(String) to handle timezone conversion to seconds and nanos. See Timestamp format for details.
address	user_data.user_identifiers[].address	Maps to an AddressInfo object. See Address object mapping.
gpp_string	No equivalent	Consent must be mapped to the request-level or event-level Consent object. See the Privacy and consent overview.
gpp_sid	No equivalent	Consent must be mapped to the request-level or event-level Consent object. See the Privacy and consent overview.
mmt_only	No equivalent
click_id	ad_identifiers.gclid	Map to the Google Click ID (gclid). See AdIdentifiers for more details.
impression_id	ad_identifiers.impression_id	See AdIdentifiers for more details.
event_ip_address	event_device_info.ip_address	See DeviceInfo for available fields.
event_user_agent	event_device_info.user_agent	See DeviceInfo for available fields.
ifa	ad_identifiers.mobile_device_id	Map to the mobile identifier for advertisers (IDFA on iOS, AdID on Android). See AdIdentifiers for more details.
landing_ip_address	ad_identifiers.landing_page_device_info.ip_address	See DeviceInfo for available fields.
landing_user_agent	ad_identifiers.landing_page_device_info.user_agent	See DeviceInfo for available fields.
age_range	No equivalent
gender	No equivalent
ext	No equivalent

Address object mapping

ECAPI (address)	Data Manager API (AddressInfo)	Notes
first_name	given_name	Maps to the given_name field in AddressInfo. Follow the formatting and hashing guidelines. You can also encrypt the hashed attributes of an address.
last_name	family_name	Maps to the family_name field in AddressInfo. Follow the formatting and hashing guidelines. You can also encrypt the hashed attributes of an address.
street	No equivalent	Not supported in the Data Manager API
city	No equivalent	Not supported in the Data Manager API
state	No equivalent	Not supported in the Data Manager API
country_code	region_code	Do not hash. Maps to the region_code field in AddressInfo. Follow the formatting guidelines.
postal_code	postal_code	Do not hash. Maps to the postal_code field in AddressInfo. Follow the formatting guidelines.
address_type	No equivalent	Not supported in the Data Manager API
ext	No equivalent

Item object mapping

Tip: Refer to the Add cart data section in the Send events guide for more information on which fields to include in cart data for each event ingestion use case.

ECAPI (item)	Data Manager API (Item)	Notes
id	item_id	Required for Google Analytics events. Set to a standard, unique identifier for the item.
No equivalent	merchant_product_id	Required for Floodlight conversions and Google Ads conversions with cart data. Set to the product ID within the Merchant Center account.
name	additional_item_parameters	Map as item_name in the additional_item_parameters list.
price	unit_price
discount	additional_item_parameters or custom_variables	Map as discount in additional_item_parameters (for Google Analytics) or as a custom variable in custom_variables (for Google Ads).
quantity	quantity	Convert the float value to an integer (int64).
brand	additional_item_parameters	Map as item_brand in the additional_item_parameters list.
affiliation	additional_item_parameters	Map as affiliation in the additional_item_parameters list.
category	additional_item_parameters	Map as item_category in the additional_item_parameters list.
cattax	No equivalent
item_coupon	additional_item_parameters	Map as coupon in the additional_item_parameters list.
item_list_id	additional_item_parameters	Map as item_list_id in the additional_item_parameters list.
item_list_name	additional_item_parameters	Map as item_list_name in the additional_item_parameters list.
item_item_variant	additional_item_parameters	Map as item_variant in the additional_item_parameters list.
item_location_id	additional_item_parameters	Map as location_id in additional_item_parameters.
ext	No equivalent

Standard event names

ECAPI standard events heavily align with Google Analytics naming conventions.

• If you're sending events to a Google Analytics data stream, the event_name field is required.
• Check out the Google Analytics recommended events reference for associated fields, parameters, and sample Data Manager API ingestion requests for each event.
• You can also send Custom events provided they follow the Event naming rules.

Most ECAPI standard events (such as purchase, add_to_cart, begin_checkout, search, and refund) have the same event name as Google Analytics recommended events. However, there are a few exceptions where Google Analytics uses present tense instead of past tense:

• viewed_item maps to view_item
• viewed_item_list maps to view_item_list
• viewed_cart maps to view_cart

Example requests

The following tabs show a comparison between an ECAPI conversion event payload and its representation as a valid Data Manager API IngestEventsRequest.

ECAPI

Here's a sample JSON payload conforming to the ECAPI specification.

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

Data Manager API

Here's a sample IngestEventsRequest for the formatted, hashed, and encoded event data. This is for a Google Ads destination, as indicated by the GOOGLE_ADS account type in the destination.

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}