Skip to main content

Events API

When, why, and how to use the Events API

Updated over a week ago

The Events API provides advertisers with a reliable server-to-server connection between Roku Ads Manager and an advertiser's marketing data (e.g., website, app, and offline events), while giving you the ability to customize the information that you share with Roku.

This article describes how to use the Events API, and why.

Consider these articles for more information on events:


General Events API Information

What is it?

The Events API is a server-to-server integration that allows you to share data directly with Roku for measurement, campaign optimization, and custom audience targeting (coming soon).


The Events API enables:

  • Server-side tracking: Avoid cookie-dependency for more accurate and reliable data.

  • Consolidated insights: Measure conversions across multiple channels with a single API.

  • Better control: Easily customize what data you share and when.

Why is it Important?

The Events API can drive unique advantages for your business:

  • Improved performance: Leverage more complete data for better campaign optimization and conversion attribution.

  • Robust targeting: Create event-based custom audiences in real time to re-engage your existing customers.

  • Competitive advantage: Gain deeper insights than pixel-reliant competitors.

  • Sustainable solutions: The Events API, along with an existing Pixel, offers a more durable measurement solution amidst changes in the advertising ecosystem.

What is the difference between Roku’s Events API and Roku’s Pixel tracking solutions?

Both Roku Pixel tracking and Roku Events API allow you to share event data with Roku. However, the Events API sends data directly from your servers to Roku’s servers, rather than through your customer’s browser, and thus doesn’t rely on browser-based cookies like the pixels (which can be limited by browser restrictions, ad blockers, and user cookie preferences).

When to use Pixels vs Events API?

Choosing between the Events API and pixel tracking depends on your business’s specific needs, goals, and resources. Where feasible, we recommend using both tools together to provide you with the most accurate and complete tracking data and insights.

  • Pixels are ideal for: Beginners, businesses with basic tracking needs, and quick, user-friendly implementations.

  • Events API is ideal for: Complex tracking requirements and advanced marketers seeking deeper insights.

Below we will compare the pros and cons of Pixels and Events API:

Pros

Cons

Pixels

  • Easy to set up: Simple code snippet placed on your website/app

  • No technical expertise needed: No server-side integration required

  • Faster implementation: Up and running quickly with minimal resources

  • Widely supported: Works across various platforms and devices

  • Limited data:  The data payload each event can send using the pixel will not be as rich if those were sent using events API

  • Relies on cookies: Vulnerable to cookie blocking and [ad blocking software]

  • Less accurate: Prone to data loss and attribution errors

Events API

  • Server-side tracking:  More reliable connection to share data

  • Better attribution: Accurately track conversions across multiple touchpoints

  • Complex Technical setup: Requires developer involvement and server integration. Longer setup time and potential technical hurdles may arise.

  • Costly integration: Depending on development needs


Events API setup

Authentication

An API key is needed in the Authorization header of your HTTP request to send data.

To generate an API key, visit the Settings page within the Events tab of Ads Manager.

Next, click “Generate new API key.” This action can only be taken by Organization or Account Admins.

API keys do not expire. However, if you believe your API key has been compromised, you can revoke an existing API key and create a new one.

Make sure to pass the generated API key in the authorization header in the Events API requests.

Events API reference

The following table summarizes the basic information for the Events API:

Item

Description

Endpoint

Protocol

Event API calls may only be sent using HTTPS.

Methods

The Events APIs support the following REST methods for onboarding event data:

  • POST. Add one or more conversion events (see JSON body for the fields that may be included in the JSON body of the POST request).

Format

The Events API supports JSON-formatted data.

Header

Requests to the Events API require the following headers:

  • Accept: application/json

  • Content-Type: application/json

  • Authorization: Bearer <JSON web token [JWT])> (see Authentication API reference for more information on generating and providing this token).  

Response Codes

The Event APIs return one of the following response codes:

  • 200: OK

  • 210: Partial Success

  • 400: Bad request (required fields are missing from the payload; a description of the error is returned)

  • 401: Unauthorized

  • 403: Forbidden (if an invalid partner)

  • 404: Not found

  • 500: Internal Server Error


Available Endpoints

Endpoint

Method

Description

/v1/events

POST

Submit conversion events

/v1/test_events

POST

Test event submission without processing

JSON body

You can include the following parameters in the JSON body of a POST request to the Events API: 

Parameter

Type

Required/Optional

Description

event_group_id 

string

Required

The ID that all these events belong to. An event group is used to represent one online property such as a website or app/channel.

events

array of objects

Required

Events you wish to pass to Roku through the Events API. See the below table for details on fields that make up a single event object.


We support a maximum of 1000 events in this array.
We validate each event independently and accept the valid ones. Invalid events are sent back in the response as failed events. See the response table later in this document for more details.


Event Object Parameters

You can include the following parameters in the event object:

Parameter

Type

Required/Optional

Description

event_id

string

Optional

The unique string generated by the site. Used for deduplication: If you install the Roku Pixel (client-side) on your website and are sending events using the Events API (server side), then make sure to pass this field from both client and server side to eliminate duplicate fires from client-side and server-side.
Deduplication will only work if the two events are fired within 10 minutes of each other with the same event ID.

event_name

string

Required

  1. ACHIEVE_LEVEL: A user reaches a certain level that you have defined in your game.

  2. ADD_PAYMENT_INFO: When payment information is added in the checkout flow.

  3. ADD_TO_CART: When a product is added to the shopping cart.

  4. ADD_TO_WISHLIST: When a product is added to a wishlist.

  5. APP_INSTALL: When a user installs an app, or first time an app is opened/launched.

  6. COMPLETE_REGISTRATION: When a registration form is completed.

  7. CONTACT: When a person initiates contact with your business via telephone, SMS, email, chat, etc.

  8. CUSTOMIZE_PRODUCT: When a person customizes a product.

  9. DONATE: When a person donates funds to your organization or cause.

  10. DOWNLOAD: A download of a doc, info, or service.

  11. FIND_LOCATION: When a person searches for a location of your store via a website or app, with an intention to visit the physical location.

  12. INITIATE_CHECKOUT: When a person enters the checkout flow prior to completing the checkout flow.

  13. LEAD: When a sign up is completed.

  14. PAGE_VIEW: This is the default pixel tracking page visits.

  15. PURCHASE: When a purchase is made or checkout flow is completed.

  16. SCHEDULE: When a person books an appointment to visit one of your locations.

  17. SEARCH: When a search is made.

  18. SIGN_UP: When a person applies for a product, service, or program you offer.

  19. START_TRIAL: When a person starts a free trial of a product or service you offer.

  20. SUBSCRIBE: When a person applies to a start a paid subscription for a product or service you offer.

  21. SUBSCRIPTION_CANCELLATION: When a subscription is cancelled by the user.

  22. SUBSCRIPTION_RENEWAL: When a subscription is auto-renewed - this could be system generated event.

  23. UNLOCK_ACHIEVEMENT: A user unlocks a certain achievement that you have defined in your app.

  24. VIEW_CONTENT: Used to capture a VIEW in app whether a particular movie/show was streamed.

event_source

string

Optional

Sources of conversion events include, but are not limited to, the following:

  • chat: Conversion occurs during an online chat conversation.

  • ctv_app: Conversion occurs within a connected TV (CTV) advertising channel.

  • email: Conversion occurs during an email communication.

  • mobile_app: Conversion occurs during the use of a mobile phone or tablet.

  • phone_call: Conversion occurs during a partner phone call.

  • physical_store: Conversion occurs when the prospective customer is in your physical retail space.

  • roku: Conversion occurs within a streaming app on a customer's Roku device (Roku TV, set-top-box [STB], streaming stick, soundbar).

  • system-generated: Conversion happens automatically (for example, a monthly subscription that is auto-paid).

  • website: Conversion occurs on a website.

  • other: Conversion occurred in a manner not included in this list.

event_source_url

string

Optional

The web page URL where the event originated. The protocol may be HTTP or HTTPS.

event_time

integer

Required

A UNIX timestamp in epoch seconds when the event occurred.

event_type

string

Required

Set this to "conversion". This field may support other event types (for example, "clicks", "impressions", and so on) in the future.

referrer_url

string

Optional

The web page URL where the user was directly before landing on the subject URL.
The referrer URL may be used for attribution only; it cannot be used for optimization, targeting, or graphing.

user_data

object

Required

A map containing customer information data. One of the following values must be provided or the request will be rejected: email, aGA, AID, aDX, aGI, or aRI.

custom_data

object

Optional

A map that includes additional business data about the event such as revenue, SKU, order ID, and other identification data. 

opt_out

string

Optional

Limited Data Use (LDU) is a data processing option that lets you limit how your event data is used in Roku's systems and helps to better support your compliance efforts with various US state privacy laws.

A value of "true" triggers the LDU flag. See the LDU article for more detailed implementation instructions.

partner_name

String

Optional

Name of the partner, in cases where a 3rd party is sending events on behalf of an advertiser


User Data Object Parameters

The user_data object may include the following parameters:

Values requiring hashing (SHA-256)

Parameter

Description

em

Hashed email address (must be normalized prior to hashing)

ph

Hashed phone number (must be normalized prior to hashing)

fn

First name

ln

Last name

ge

Gender (should be one of male, female, unknown)

db

Date of birth (only accepted format yyyy-mm-dd)

Normalizing Raw Data Before Hashing

Raw email addresses and phone numbers must be normalized before being hashed. To normalize, follow these rules:

  • Email addresses:

    • Lowercase the email address.

    • Trim all leading and trailing whitespaces.

    • Remove all characters after "+" and before "@" (for example, normalize myname+alias@isp.com to myname@isp.com).

  • Phone numbers:

    • Remove all special characters including "+" or "-".

    • Remove all zeros at the beginning of the number.

    • Trim all whitespaces.

Values that should not be hashed

Parameter

Description

ct

City (please provide complete name)

st

State (please provide complete name)

zp

Zip code

country

Country

external_id

External ID

client_ip_address

Client IP address

client_user_agent

Client user agent

subscription_id

Subscription ID

aGA

Google or Android mobile ad ID

aID

Apple mobile ad ID (IDFA)

aGI

Generic IFA

aRI

Roku identified for advertising (RIDA)

aFC

Your first-party cookie

Custom Data Object Parameters

The custom_data object is optional and may include the following parameters:

Field

Type

Description

content_category

string

The category of the page/product.

content_ids

array of integers or strings

The product IDs associated with the event such as SKUs (for example, ['ABC123', 'XYZ789']).

content_name

string

The name of the page/product.

content_type

string

Either the product or product_group based on the content_ids or contents being passed.
If the IDs being passed in content_ids or contents are IDs of products, the value should be product.
If product group IDs are being passed, then the value should be product_group.

contents

array of objects

An array of JSON objects that contains the quantity and the International Article Number (EAN) when applicable, or other product or content identifier(s).

  • Required fields: id, quantity, and price.

  • Optional field: delivery_category

  • Example: [{'id': ‘ABC123', ‘quantity': '2’, 'price': 10, 'delivery_category': 'in_store'}, {'id': 'XYZ789', 'quantity': '2’, 'price': 5}].

currency

string

The currency for the value specified.


List of currencies currently supported: AED, ARS, AUD, BDT, BHD, BIF, BOB, BRL, CAD, CHF, CLP, CNY, COP, CRC, CZK, DKK, DZD, EGP, EUR, GBP, GTQ, HKD, HNL, HUF, IDR, ILS, INR, ISK, JPY, KES, KHR, KRW, KWD, KZT, MAD, MOP, MXN, MYR, NGN, NIO, NOK, NZD, OMR, PEN, PHP, PHP, PKR, PLN, PYG, QAR, RON, RUB, SAR, SEK, SGD, THB, TRY, TWD, UAH, USD, VES, VND, ZAR.

num_items

integer

The number of items when checkout was initiated.

predicted_ltv

integer, float

The predicted lifetime value of a subscriber, as defined by the advertiser and expressed as an exact value.

search_string

string

The string entered by the user for the search.

status

string

Indicates the status of an order or service.

value

integer or float

The total amount of the value of all products being purchased.


The price field is the price for a single item; the value is the total price of the order.


Please make sure to include this field with all purchase event for Return on Ad Spend (ROAS) reports.

order_id

string

The order ID for this transaction (for example, 'order1234').

purchase_type

string

This is to indicate one of the following types of purchase: first_time_purchase and repeat_purchase

delivery_category

string

The type of delivery for a purchase event. This may be one of the following values:

  • in_store: Customer must enter the store to get the purchased product.

  • curbside: Customer picks up their order by driving to a store and waiting inside their vehicle.

  • home_delivery: Purchase is delivered to the customer's home.

utm_source

string

Source from where the user arrived to the site

utm_medium

string

Medium from where the user arrived to the site

utm_campaign

string

Campaign from where the user arrived to the site

utm_term

string

Keyword terms from where the user arrived to the site

utm_content

string

Content from where the user arrived to the site

Response

The following parameters will be included in the response:

Parameter

Description

code

HTTP response code


The Event APIs return one of the following response codes:

  • 200: OK

  • 210: Partial Success

  • 400: Bad request (required fields are missing from the payload; a description of the error is returned)

  • 401: Unauthorized

  • 403: Forbidden (if an invalid partner)

  • 404: Not found

  • 500: Internal Server Error

description

It can be one of the following:

  • all events were processed

  • all events failed

  • some events could not be processed

events_received

The total event sent in the payload

failed_events

Contains the raw request body for only invalid events.


We add a field called errors with each failed event. This field would list the reasons why the event was marked as Invalid.


API Endpoint Details

1. Events API

POST /v1/events

Submit conversion events to be processed by the Roku Ads Manager.

Example Request:

{
"event_group_id": "example_website_123",
"events": [
{
"event_id": "unique_event_id_123",
"event_name": "PURCHASE",
"event_type": "conversion",
"event_time": 1621436800,
"event_source": "website",
"event_source_url": "https://example.com/checkout/confirmation",
"referrer_url": "https://example.com/product/123",
"user_data": {
"is_hashed": true,
"em": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a",
"ph": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
"client_ip_address": "192.168.1.1",
"client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
},
"custom_data": {
"value": 99.99,
"currency": "USD",
"content_type": "product",
"order_id": "order_12345",
"contents": [
{
"id": "product_123",
"quantity": "1",
"price": 99.99,
"delivery_category": "home_delivery"
}
]
},
"opt_out": "false"
}
]
}

Example Response:

{
"code": 200,
"description": "all events were processed",
"events_received": 1,
"failed_events": []
}

2. Test Events API

POST /v1/test_events

Test your event submission without actually processing the events. This is useful for validating your payload format.

Example Request:

{
"event_group_id": "example_website_123",
"events": [
{
"event_id": "test_event_id_456",
"event_name": "ADD_TO_CART",
"event_type": "conversion",
"event_time": 1621436800,
"event_source": "website",
"event_source_url": "https://example.com/cart",
"user_data": {
"is_hashed": true,
"em": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a",
"aGA": "5e2d9c1a-9e9c-4d5b-9c1a-9e9c4d5b9c1a"
},
"custom_data": {
"value": 24.99,
"currency": "USD",
"contents": [
{
"id": "product_456",
"quantity": "1",
"price": 24.99
}
]
}
}
]
}

Example Response:

{
"code": 200,
"description": "all events were processed",
"events_received": 1,
"failed_events": []
}


Error Handling

Common Error Scenarios

1. Missing Required Fields: When mandatory fields like event_name, event_type, or user_data identifiers are missing

{

"code": 400,

"description": "all events failed",

"events_received": 1,

"failed_events": [

{

"event_id": "error_event_id",

"errors": {

"event_name": "event_name is required",

"user_data": "At least one user identifier is required"

}

}

]

}

2. Invalid Enum Values: When a field contains an unrecognized value

{
"code": 400,
"description": "all events failed",
"events_received": 1,
"failed_events": [
{
"event_name": "INVALID_EVENT",
"errors": {
"event_name": "Invalid event name: INVALID_EVENT. Event name must be one of the supported values."
}
}
]
}


Testing and Debugging

The following resources can be used to test and debug your Event API integration.

Resource

URL

Description

Test Events API Endpoint

A POST method that enables you to send a test request using the same JSON body as the Events API.


This endpoint is for integration testing purposes only and does not ingest any data into the platform.

Did this answer your question?