Events API

Pros

Cons

Pixels

Events API

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:

Format

The Events API supports JSON-formatted data.

Header

Requests to the Events API require the following headers:

Response Codes

The Event APIs return one of the following response codes:

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

event_source

string

Optional

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

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

Normalizing raw email addresses and phone numbers.

Raw email addresses and phone numbers must be normalized before being hashed.

To normalize, follow these rules:

Do not hash

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.

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

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:

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

code

HTTP response code

The Event APIs return one of the following response codes:

description

It can be one of the following

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.

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.