Server-to-Server (S2S) API Events¶
Note
The S2S event API is under active development. Although the API is generally stable, it may change. Event processing is not yet fully complete. Send us a message if you have questions.
Event format¶
Below is an event’s JSON structure. You can send more than one event per request, but please limit it to no more than one hundred events. For additional properties and examples, please review the following event-specific sections.
[{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"event_name": "<EVENT_NAME>",
"event_attributes": "<EVENT_ATTRIBUTES>",
"external_data": "<EXTERNAL_DATA>",
"ip": "<IP>",
"user_agent": "<USER_AGENT>",
"conversion_value": "<CONVERSION_VALUE>",
"currency": "<CURRENCY>",
"page_location": "<PAGE_LOCATION>",
"device_os": "<DEVICE_OS>",
"device_type": "<DEVICE_TYPE>",
"package_app_name": "<PACKAGE_APP_NAME>",
"package_app_version": "<PACKAGE_APP_VERSION>",
"timestamp": "<TIMESTAMP>",
"identifiers": {
"adct": "<ADCT>",
"email": "<EMAIL_ADDRESS>",
"email_sha256": "<EMAIL_SHA256>",
"email_md5": "<EMAIL_MD5>",
"device_id": "<DEVICE_ID>",
"first_party_cookie": "<FIRST_PARTY_COOKIE>",
"user_id": "<USER_ID>"
}
}]
Required Fields¶
advertisable_eidThe unique identifier for your AdRoll advertisable.
pixel_eidThe pixel identifier associated with your AdRoll advertisable.
event_nameEvent type. One of the following:
pageView: See Page view event.homeView: See Home view event.productSearch: See Product search event.addToCart: See Add to cart event.purchase: See Purchase event.highValuePage: See High-value page event.gatedContent: See Gated content event.demoRequest: See Demo request event.signupPlan: See Signup plan event.signupTrial: See Signup trial event.contactSales: See Contact sales event.liveChat: See Live chat event.formFill: See Form fill event.
page_locationThe full URL where the event occurred. When using a mobile app, you should build a “fake” URL using the format mentioned in Mobile app URLs.
ipIPv4 or IPv6 user address.
identifiersCurrently you must at least specify a
first_party_cookie, additional identifiers are recommended. This requirement is expected to change over time.adct: Ad Click Token parameter retrieved after an ad click. See Click ID (adct).email: Email address in clear text. See Email.email_sha256: Email address hashed using SHA-256. See Email.email_md5: Email address hashed using MD5. See Email.device_id: mobile device ID. See Mobile device ID.first_party_cookie: First-party cookie retrieved from AdRoll pixel or generated. See First-Party Cookie.user_id: Custom user ID. See Custom user ID.
Optional Fields¶
event_attributesSee the Event types for the format of this field.
user_agentOptional for requests originating from a mobile app. When the journey begins on the web, capture and send the browser’s user agent.
conversion_valueMonetary value of the event (e.g., purchase amount).
currencyThe currency of the
conversion_value(e.g.,USD). Supports three-letter ISO 4217 currency codes.timestampUTC timestamp in seconds of when the event should be considered to have taken place. The current time will be used if omitted. You can use a decimal point if you want to specify milliseconds.
device_osThe operating system of the user’s device for mobile events.
device_typeThe user’s device type for mobile events.
package_app_nameYour application’s package name for mobile events.
package_app_versionYour application’s package version for mobile events.
external_dataJSON string containing any additional event data that is useful to your application.
Specifying products¶
Most events let you specify a list of products relevant to the event. Each product can contain the following fields:
product_idThe ID of the product on your site
product_groupThe group or department of the product on your site
priceThe price of the product added. The currency must match what is specified in the event-level
currencyfield.quantityQuantity of this product added to cart or purchased
categoryOther categorization for product on your site
Mobile app URLs¶
When sending mobile app events, you can create a fake URL for the page_location field. This allows you to use URL audiences for campaign targeting. This URL should simulate a web-like structure using key app-related fields. Start with a domain you manage (the domain doesn’t need to be reachable), and append query parameters derived from the mobile app data. Include the following optional event fields:
device_osdevice_typepackage_app_namepackage_app_version
For example, a valid mobile app URL could look like this:
https://app.example.com?device_os=iOS&device_type=phone&package_app_name=com.example.TradingApp&package_app_version=14.1.3
Event types¶
The following sections describe the purpose and format for supported events. Please let us know if you need additional events to better represent your needs.
B2C event types¶
Page view event¶
Event name: pageView
This event means a user has viewed a page on your website or app. It serves as the default event type when a more specific event (such as “add to cart” or “purchase”) isn’t available. Tracking page views provides insights into user behavior, popular content, and overall engagement.
Required attributes:
None
Optional attributes:
event_attributes.productsAn array of products shown on the page. See Specifying products.
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "pageView",
"event_attributes": {
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"quantity": 1,
"price": "56.78",
"category": "top-sellers"
}
]
}
}
Home view event¶
Event name: homeView
This event means a user has viewed the homepage of your website or app. It indicates an initial entry point or a return to the main landing page, providing insight into user engagement at the most general level.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "homeView"
}
Product search event¶
Event name: productSearch
This event means a user has searched for products on your website or app. It indicates active engagement and a potential interest in making a purchase.
Required attributes:
None
Optional attributes:
event_attributes.keywordsSearch terms entered by the user
event_attributes.productsAn array of products returned as results. See Specifying products.
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "productSearch",
"event_attributes": {
"keywords": "shoes",
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"price": "56.78",
"category": "top-sellers"
},
{
"product_id": "GHIJKL-67890",
"product_group": "womens-fashion",
"price": "61.23",
"category": "new-items"
},
{
"product_id": "MNOPQR-98765",
"product_group": "womens-fashion",
"price": "57.89"
},
{
"product_id": "STUVWX-43210",
"product_group": "womens-fashion",
"price": "63.45",
"category": "new-items"
}
]
}
}
Add to cart event¶
Event name: addToCart
This event means a user has added a product to their shopping cart.
Required attributes:
None
Optional attributes:
currencyCurrency of the conversion value
event_attributes.productsAn array of products added to the cart. See Specifying products.
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "addToCart",
"currency": "USD",
"event_attributes": {
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"quantity": 2,
"price": "56.78",
"category": "top-sellers"
},
{
"product_id": "UVWXYZ-98765",
"product_group": "electronics",
"quantity": 1,
"price": "123.45",
"category": "new-items"
}
]
}
}
Purchase event¶
Event name: purchase
This event means a user has completed a purchase.
Required attributes:
None
Optional attributes:
conversion_valueThe total conversion value of this purchase
currencyCurrency of the conversion value
event_attributes.order_idID of the order on your site
event_attributes.productsAn array of purchased products. See Specifying products.
external_dataJSON string containing for any additional conversion data that is useful to your needs. It’s value is available in Granular Conversion Reports.
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "purchase",
"conversion_value": "113.56",
"currency": "USD",
"event_attributes": {
"order_id": "ABCDEFGH-1234-5678-9012-IJKLMNOPQRST",
"products": [
{
"product_id": "ABCDEF-12345",
"product_group": "womens-fashion",
"quantity": 2,
"price": "56.78",
"category": "top-sellers"
}
]
},
"external_data": "{\"foo\": \"bar\"}"
}
B2B/ABM event types¶
High-value page event¶
Event name: highValuePage
This event signifies a user has visited a page deemed to be of high value. This could be a pricing page, a key feature page, or any other page that indicates strong user interest or intent.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "highValuePage"
}
Gated content event¶
Event name: gatedContent
This event indicates a user has accessed gated content, such as a whitepaper, ebook, or exclusive article, typically after providing their information (e.g., email address).
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "gatedContent"
}
Demo request event¶
Event name: demoRequest
This event means a user has requested a product demonstration. This is a strong indicator of interest and a high-intent action.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "demoRequest"
}
Signup plan event¶
Event name: signupPlan
This event signifies a user has completed a signup process for a specific plan or subscription.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "signupPlan"
}
Signup trial event¶
Event name: signupTrial
This event indicates a user has signed up for a free trial of your product or service.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "signupTrial"
}
Contact sales event¶
Event name: contactSales
This event means a user has initiated contact with your sales team, typically through a form submission or a direct click-to-call/email.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "contactSales"
}
Live chat event¶
Event name: liveChat
This event signifies a user has engaged in a live chat session.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "liveChat"
}
Form fill event¶
Event name: formFill
This event indicates a user has completed a form, excluding those covered by more specific events like demo requests or contact sales.
Required attributes:
None
Optional attributes:
None
Below is an example event:
{
"advertisable_eid": "<ADVERTISABLE_EID>",
"pixel_eid": "<PIXEL_EID>",
"page_location": "<PAGE_LOCATION>",
"ip": "<IP>",
"identifiers": {
"first_party_cookie": "<FIRST_PARTY_COOKIE>"
},
"event_name": "formFill"
}