Events API | Roku Self Serve Help Center

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.

General Events API Information
Events API Set Up
Available End Points
Event Object Parameters
User Data Object Parameters
API Endpoint Details
Error Handling
Testing & Debugging

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	https://events.ads.rokuapi.net/v1/events
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	ACHIEVE_LEVEL: A user reaches a certain level that you have defined in your game. ADD_PAYMENT_INFO: When payment information is added in the checkout flow. ADD_TO_CART: When a product is added to the shopping cart. ADD_TO_WISHLIST: When a product is added to a wishlist. APP_INSTALL: When a user installs an app, or first time an app is opened/launched. COMPLETE_REGISTRATION: When a registration form is completed. CONTACT: When a person initiates contact with your business via telephone, SMS, email, chat, etc. CUSTOMIZE_PRODUCT: When a person customizes a product. DONATE: When a person donates funds to your organization or cause. DOWNLOAD: A download of a doc, info, or service. 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. INITIATE_CHECKOUT: When a person enters the checkout flow prior to completing the checkout flow. LEAD: When a sign up is completed. PAGE_VIEW: This is the default pixel tracking page visits. PURCHASE: When a purchase is made or checkout flow is completed. SCHEDULE: When a person books an appointment to visit one of your locations. SEARCH: When a search is made. SIGN_UP: When a person applies for a product, service, or program you offer. START_TRIAL: When a person starts a free trial of a product or service you offer. SUBSCRIBE: When a person applies to a start a paid subscription for a product or service you offer. SUBSCRIPTION_CANCELLATION: When a subscription is cancelled by the user. SUBSCRIPTION_RENEWAL: When a subscription is auto-renewed - this could be system generated event. UNLOCK_ACHIEVEMENT: A user unlocks a certain achievement that you have defined in your app. 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	https://events.ads.rokuapi.net/v1/test_events	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.