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_eid

The unique identifier for your AdRoll advertisable.

pixel_eid

The pixel identifier associated with your AdRoll advertisable.

event_name

Event 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_location

The 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.

ip

IPv4 or IPv6 user address.

identifiers

Currently 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_attributes

See the Event types for the format of this field.

user_agent

Optional for requests originating from a mobile app. When the journey begins on the web, capture and send the browser’s user agent.

conversion_value

Monetary value of the event (e.g., purchase amount).

currency

The currency of the conversion_value (e.g., USD). Supports three-letter ISO 4217 currency codes.

timestamp

UTC 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_os

The operating system of the user’s device for mobile events.

device_type

The user’s device type for mobile events.

package_app_name

Your application’s package name for mobile events.

package_app_version

Your application’s package version for mobile events.

external_data

JSON 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_id

The ID of the product on your site

product_group

The group or department of the product on your site

price

The price of the product added. The currency must match what is specified in the event-level currency field.

quantity

Quantity of this product added to cart or purchased

category

Other 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_os

• device_type

• package_app_name

• package_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.products

An 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.keywords

Search terms entered by the user

event_attributes.products

An 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:

currency

Currency of the conversion value

event_attributes.products

An 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_value

The total conversion value of this purchase

currency

Currency of the conversion value

event_attributes.order_id

ID of the order on your site

event_attributes.products

An array of purchased products. See Specifying products.

external_data

JSON 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"
}