Skip to main content
All CollectionsPixels & Events
Events API
Events API

When, why, and how to use the Events API

Updated over 2 months 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:

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 (coming soon): 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

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.

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

A list of all supported events. This may be one of the following values:

  • AD_VIEW: Ad views.

  • ADD_PAYMENT_INFO: Payment information is added in the checkout flow.

  • ADD_TO_CART: A product is added to the shopping cart.

  • ADD_TO_WISHLIST: A product is added to a wish list.

  • APP_INSTALL:  A mobile app is installed.

  • COMPLETE_REGISTRATION: A registration form is completed.

  • CONTACT: A customer initiates contact with your business via telephone, SMS, email, chat, or other contact method.

  • CUSTOMIZE_PRODUCT: A customer customized a product.

  • DONATE: A donation is made to your organization or cause.

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

  • FIND_LOCATION: A customer searches for your physical store location via a website or app, with an intention to visit.

  • INITIATE_CHECKOUT: A customer enters the checkout flow prior to completion.

  • LEAD: A customer completes a sign-up form. 

  • PAGE_VIEW: The default number of pixel tracking page visits.

  • PURCHASE: A purchase or checkout flow is completed.

  • SCHEDULE: A customer books an appointment to visit one of your locations.

  • SEARCH: A search query is made.

  • SIGN_UP: A sign-up event.

  • START_TRIAL: A free trial is initiated.

  • SUBMIT_APPLICATION: A customer applies for an offered product, service, or program. 

  • SUBSCRIBE: A customer starts a paid subscription for an offered product or service.

  • SUBSCRIPTION_CANCELLATION: A customer cancels a paid subscription for a product or service.

  • SUBSCRIPTION_RENEWAL: A customer renews a paid subscription for a product or service.

  • UNLOCK_ACHIEVEMENT: A customer unlocks an achievement or a reward.

  • VIEW_CONTENT: A customer visits a web page of interest (for example, a product page or landing page). This event is not specific about the actions on the web page. This event can also be used to capture an in-app VIEW, whether it is for a particular webpage or content such as a movie or television show.

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.

This may be one of the following values (note whether hashing is required for the value):

Hashing (SHA-256) required

  • 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 email addresses and phone numbers.

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.

Do not hash

  • ct: city (please provide complete name)

  • st: state  (please provide complete name)

  • zp: zip code  (please provide complete name)

  • 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)

  • aDX: Roku Cookie 3P cookie

  • aGI: generic IFA

  • aRI: Roku identified for advertising (RIDA)

  • aFC: your first-party cookie

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.

In addition to the above parameters, you may also custom_data, which is a map that includes additional business data about the event such as revenue, SKU, order ID, and other identification data. 

This is optional, and may be one of the following values:

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

boolean

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

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

event_trace_id

A unique ID for a particular request is sent to the events API.

You can use this ID with the debug endpoint (see below) to see if a request was successfully processed or had failures. event_trace_id expires after 7 days.

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.

Request 

The following sample demonstrates the JSON body to be included in POST requests to the Events API: 

{ 
  "events": [ 
    { 
      "event_name": "string", 
      "event_type": "string", 
      "event_time": 0, 
      "user_data": { 
        "is_hashed": true, 
        "em": "string", 
        "ph": "string", 
        "ge": "string", 
        "db": "string", 
        "ln": "string", 
        "fn": "string", 
        "ct": "string", 
        "st": "string", 
        "zp": "string", 
        "country": "string", 
        "external_id": "string", 
        "client_ip_address": "string", 
        "client_user_agent": "string", 
        "subscription_id": "string", 
        "aGA": "string", 
        "aID": "string", 
        "aDX": "string", 
        "aGI": "string", 
        "aRI": "string", 
        "aSH": "string", 
        "aFC": "string", 
        "ga_session_id": "string", 
        "ga_client_id": "string", 
        "ga_gclid": "string", 
        "ga_measurement_ids": [ 
          "string" 
        ] 
      }, 
      "custom_data": { 
        "value": 0, 
        "currency": "string", 
        "delivery_category": "string", 
        "num_items": "string", 
        "order_id": "string", 
        "contents": [ 
          { 
            "delivery_category": "IN_STORE", 
            "id": "string", 
            "item_price": 0, 
            "quantity": "string" 
          } 
        ], 
        "purchase_type": "string", 
        "content_category": "string", 
        "content_ids": [ 
          "string" 
        ], 
        "content_type": "string", 
        "utm_source": "string", 
        "utm_medium": "string", 
        "utm_campaign": "string", 
        "utm_term": "string", 
        "utm_content": "string", 
        "content_name": "string", 
        "predicted_ltv": "string", 
        "search_string": "string", 
        "status": "string" 
      }, 
      "event_source_URL": "string", 
      "referrer_URL": "string", 
      "event_id": "string", 
      "event_source": "string",
      "opt_out": "false"
    } 
  ], 
  "event_group_id": "string" 
}

Response

The following sample demonstrates the JSON-formatted data returned by the Events API: 

{ 
  "code": 210, 
  "events_received": 10, 
  "description": "string", 
  "event_trace_id": "string", 
  "failed_events": [{ 
    "event_name": "string", 
    "event_type": "string", 
    "event_time": 0, 
    "user_data": { 
 
      "em": "string", 
      "ph": "string", 
      "ge": "string", 
      "db": "string", 
      "ln": "string", 
      "fn": "string", 
      "ct": "string", 
      "st": "string", 
      "zp": "string", 
      "country": "string", 
      "external_id": "string", 
      "client_ip_address": "string", 
      "client_user_agent": "string", 
      "subscription_id": "string", 
      "aGA": "string", 
      "aIDFA": "string", 
      "aDX": "string", 
      "aGI": "string", 
      "aRI": "string", 
      "aSH": "string" 
    }, 
    "custom_data": { 
      "value": 0, 
      "currency": "string", 
      "delivery_category": "string", 
      "num_items": "string", 
      "order_id": "string", 
      "contents": [{ 
        "delivery_category": "IN_STORE", 
        "id": "string", 
        "item_price": 0, 
        "quantity": "string" 
      }], 
      "content_category": "string", 
      "content_ids": [ 
        "string" 
      ], 
      "content_type": "string", 
      "utm_source": "string", 
      "utm_medium": "string", 
      "utm_campaign": "string", 
      "utm_term": "string", 
      "utm_content": "string" 
    }, 
    "event_source_URL": "string", 
    "referrer_URL": "string", 
    "event_id": "string", 
    "event_source": "string", 
    "status": "string", 
    "errors": { 
      "additionalProp1": "string", 
      "additionalProp2": "string", 
      "additionalProp3": "string" 
    } 
  }] 
}

Testing and Debugging

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

Debug Events Endpoint 

https://events.ads.rokuapi.net/v1/debug_events/{event_trace_id}

A GET method that enables you to pass an event_trace_id and receive the reason for a failure/partial failure of a past event that was sent by the advertiser.  

Did this answer your question?