The Event Object

The receiver accepts the full IAB ECAPI 1.0 core Event Object without modification. This page describes every field the receiver recognizes.

The canonical, machine-readable contract is the OpenAP-maintained JSON Schema (Draft 2020-12), published at:

https://ecapi.openap.tv/schemas/ecapi-1.0.schema.json

Validate your payloads against it before sending — it is authoritative where this page and the schema differ.

Contents

• Required fields
• Top-level fields
• Event types
• user_data
• user_data.uids[]
• user_data.address[]
• properties
• properties.items[]
• Vertical-specific properties
• Field-name note (IAB examples)
• Forward compatibility

Required fields

Field	Type	Notes
data_set_id	string	Your destination namespace, issued by OpenAP. Non-empty.
timestamp	integer	Unix epoch seconds of the event (not milliseconds).
event_type	string (enum)	See Event types.

Conditional requirements:

• custom_event (non-empty string) is required when event_type = "custom"; it is ignored for all other event types.
• currency_code (ISO 4217 alpha-3, e.g. USD) is required when value is set.

Top-level fields

Field	Type	Notes
data_set_id	string	Required. Destination namespace coordinated with OpenAP.
id	string	Your event ID. Records sharing (data_set_id, id) are merged — see Updating and deduplicating events. Non-empty when present.
timestamp	integer	Required. Unix epoch seconds; must be ≥ 0.
event_type	string (enum)	Required. See Event types.
custom_event	string or null	Your custom event name. Required (non-empty) when event_type = "custom".
value	number	Total monetary value of the event. When set, currency_code is required.
currency_code	string	ISO 4217 alpha-3, uppercase (pattern ^[A-Z]{3}$, e.g. USD, EUR).
source	string (enum)	Where the event originated. One of: email, website, app, phone_call, chat, physical_store, system_generated, business_messaging, other.
user_data	object	Identity and context — see user_data.
properties	object	Event detail (transaction, items, page, vertical-specific fields) — see properties.
ext	object	Free-form extension object for passthrough. Any JSON.

Event types

event_type must be one of the ECAPI 1.0 values:

Category	Values
Commerce	purchase, refund, add_to_cart, remove_from_cart, viewed_cart, viewed_item, add_to_wishlist, begin_checkout, add_payment_info, add_shipping_info, customize_product
Browsing / content	page_view, ad_impression, search, view_search_results, view_item_list, view_promotion, select_content, select_item, select_promotion, share
Leads	generate_lead, working_lead, qualify_lead, disqualify_lead, close_convert_lead, close_unconvert_lead
Lifecycle	sign_up, login, install, start_trial, subscribe, contact
Scheduling, location & custom	schedule, find_location, donate, custom
Gaming / engagement	unlock_achievement, join_group, level_up, post_score, tutorial_begin, tutorial_complete, spend_virtual_currency, earn_virtual_currency

For custom, also set custom_event to your custom event name.

user_data

Identity and contextual signals. Fields marked hashed must be normalized and SHA256-hashed before sending (see Hashing, consent, and privacy); the receiver validates them as 64-character lowercase hex strings and rejects malformed hashes.

Field	Type	Hashed?	Notes
customer_identifier	string	yes	Your normalized + hashed customer ID.
email_address	array of string	yes	Each entry is one hashed email address.
phone_numbers	array of string	yes	Each entry is one hashed phone number (E.164-normalized before hashing).
gender	string	yes	Hashed normalized value.
uids	array of object	mixed	Platform/device identifiers — see uids[].
customer_segments	array of string	no	Your segment labels (plaintext).
address	array of object	mixed	Postal addresses — see address[].
age_range	integer (1–13)	no	Banded age — see mapping below.
utcoffset	integer (−720…840)	no	User's local time as minutes ± from UTC.
ifa	string	no	Device advertising ID (identifier for advertising).
click_id	string	no	Platform click ID.
impression_id	string	no	Platform impression ID.
event_ip_address	string	no	IPv4 or IPv6 address at event time.
event_user_agent	string	no	Browser/device user-agent string at event time.
landing_ip_address	string	no	IPv4 or IPv6 address at landing time.
landing_user_agent	string	no	User-agent string at landing time.
mmt_only	boolean	no	Measurement-only flag: the event may be used for measurement but not audience activation.
gpp_string	string	no	IAB Global Privacy Platform consent string — see Consent (GPP).
gpp_sid	array of integer	no	GPP section IDs applicable to gpp_string.
ext	object	no	Passthrough.

age_range mapping: 1=18–20, 2=21–24, 3=25–29, 4=30–34, 5=35–39, 6=40–44, 7=44–49, 8=50–54, 9=55–59, 10=60–64, 11=65–69, 12=70–74, 13=75+.

user_data.uids[]

Each entry associates a hashed identifier with its source platform.

Field	Type	Hashed?	Notes
id	string	yes	The hashed identifier value (64-char lowercase hex SHA256).
source	string	no	The identifier's source/platform.
atype	integer	no	Agent type per AdCOM 1.0 List: Agent Types.
ext	object	no	Passthrough.

user_data.address[]

An array of postal address objects. Name and line fields are hashed; locality fields are sent as normalized plaintext.

Field	Type	Hashed?	Notes
first_name	string	yes	Normalized + SHA256-hashed.
last_name	string	yes	Normalized + SHA256-hashed.
street	string	yes	Normalized + SHA256-hashed street line.
postal_code	string	yes	Normalized + SHA256-hashed.
city	string	no	Lowercase Roman alphabet recommended; UTF-8 if special characters needed.
state	string	no	Lowercase Roman alphabet recommended; UTF-8 if special characters needed.
country_code	string	no	ISO 3166-1 alpha-2, lowercase (pattern ^[a-z]{2}$, e.g. us).
address_type	string (enum)	no	One of billing, shipping, unknown.
ext	object	no	Passthrough.

properties

Event detail. All fields are optional; send what applies to the event type.

Commerce and transaction

Field	Type	Notes
transaction_id	string	Your transaction/order identifier.
items	array of object	Line items — see items[].
coupon	array of string	Coupon codes applied at the event level.
shipping	number	Shipping cost.
tax	number	Tax amount.
payment_type	array of string	Payment method(s) used.
shipping_tier	string	Shipping tier selected (e.g. ground, overnight).

Page and ad context

Field	Type	Notes
page_url	string (URI)	The page URL where the event occurred.
referrer	string or null	Referring URL.
ad_source	string	Source of the ad that drove the event.
ad_platform	string	Platform the ad ran on.
ad_format	string	Ad format.
ad_unit_name	string	Ad unit name.
creative_name	string or null	Creative name.
creative_slot	string	Creative slot.
promotion_id	string	Promotion identifier.
promotion_name	string	Promotion name.
search_term	string	The search query, for search / view_search_results.

Leads

Field	Type	Notes
lead_source	string or null	Where the lead originated.
lead_status	string or null	Current lead status.
lead_reason	string or null	Reason for the status (e.g. disqualification reason).

Engagement and gaming

Field	Type	Notes
login_method	string	Method used for login / sign_up.
group_id	string or null	Group joined, for join_group.
character	string or null	Character name.
character_level	integer	Character level, for level_up.
post_score	integer	Score posted, for post_score.
achievement_id	string or null	Achievement unlocked, for unlock_achievement.
virtual_currency_name	string or null	Currency name, for spend_virtual_currency / earn_virtual_currency.
virtual_item_name	string or null	Item name, for spend_virtual_currency.

Extension

Field	Type	Notes
ext	object	Passthrough.

properties.items[]

Each entry in properties.items describes one line item.

Field	Type	Notes
id	string	Item ID (e.g. SKU).
name	string	Item name.
price	number	Unit price.
discount	number	Discount applied to the item.
quantity	number	Quantity.
brand	string	Brand.
affiliation	string	Store or affiliation the item was sold through.
category	string	Item category.
cattax	string or integer	Category taxonomy ID per AdCOM 1.0 List: Category Taxonomies.
item_coupon	string	Coupon applied to this item.
item_list_id	string	ID of the list the item was presented in.
item_list_name	string	Name of the list the item was presented in.
item_item_variant	string	Item variant (e.g. size, color).
item_location_id	string	Location associated with the item.
ext	object	Passthrough.

Vertical-specific properties

ECAPI 1.0 defines additional properties fields for specific verticals. They live alongside the common fields above.

Automotive

Field	Type	Allowed values / format
make	string	Vehicle make.
model	string	Vehicle model.
vin	string	Vehicle identification number.
body_style	string (enum)	convertible, coupe, hatchback, minivan, truck, suv, sedan, van, wagon, crossover, other
condition_of_vehicle	string (enum)	new, used
drivetrain	string (enum)	4x2, 4x4, awd, fwd, rwd, other, none
fuel_type	string (enum)	diesel, electric, flex, gasoline, hybrid, petrol, plugin_hybrid, other, none
transmission	string (enum)	automatic, manual, other, none
exterior_color	string	Exterior color.
lease_start_date	string	YYYYMMDD or YYYY-MM-DD.
lease_end_date	string	YYYYMMDD or YYYY-MM-DD.

Real estate

Field	Type	Allowed values / format
availability	string (enum)	available soon, for rent, for sale, off market, recently sold, sale pending
listing_type	string (enum)	for rent by agent, for rent by owner, for sale by agent, for sale by owner, foreclosed, new construction, new listing

Travel

Field	Type	Allowed values / format
arrival_date	string	YYYYMMDD or YYYY-MM-DD.
departure_date	string	YYYYMMDD or YYYY-MM-DD.
destination_airport	string	IATA 3-letter airport code, uppercase (e.g. JFK).
destination_ids	string	Destination identifier(s).

Field-name note (IAB examples)

OpenAP follows the ECAPI 1.0 prose field names: email_address, address, customer_segments, and item_* (singular item_ prefix). The IAB examples.md sample uses some divergent plural/legacy spellings (email_addresses, addresses, customer_segment, items_*). If you copy the IAB example verbatim, those divergent fields are accepted but not recognized as the corresponding identity/commerce fields — use the names above.

Forward compatibility

Unknown fields encountered at validation time are accepted and preserved (routed into the event's ext). This lets you adopt additive ECAPI 1.x changes without waiting on a receiver update. Non-additive changes are published under a new versioned path (/v2/events, etc.).