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.

    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

    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

    ECAPI ( item ) Data Manager API ( Item ) Notes
    id
    		item_id Requiredfor Google Analytics events. Set to a standard, unique identifier for the item.
    No equivalent
    		 merchant_product_id Requiredfor 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.

    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 
  
 } 
  
 ] 
  
 } 
  
 } 
  
 ] 
 }
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: