Configure events for Roku

The Roku Conversions API (CAPI) lets your brand send conversion events — such as purchases, sign-ups, and trial starts — to Roku. Roku uses these events to optimize campaigns, build event-based custom audiences, and attribute conversions for return on ad spend (ROAS) measurement.

Send conversion events to Roku using the Roku Conversions API (CAPI) to power campaign optimization, event-based custom audiences, and conversion attribution (ROAS). Each row returned by your query is sent as a single conversion event carrying a Roku event type, an event timestamp, and one or more hashed customer identifiers.

Amperity hashes customer identifiers with SHA-256 before sending them; raw identifier values never leave Amperity. See the Roku Conversions API reference for more information.

Beta

The Roku CAPI connector is currently in beta. Contact your Amperity representative to learn more.

Caution

The values for email, phone, given_name, surname, gender, and birthdate sent to Roku are SHA-256 hashed automatically by Amperity before sending. Do not use the TO_HEX() function with the email, phone, given_name, surname, gender, and birthdate fields for queries that return results for Roku.

Get details

Review the following details before configuring credentials for Roku and before configuring Amperity to send conversion events to Roku.

	Credential settings CAPI token Required A bearer token (JWT) that authorizes Amperity to send events to the Roku Conversions API. Generate the token in Roku Ads Manager under Events > CAPI. Generating a token requires the Admin or Org Admin role. The token does not expire but can be revoked; to rotate it, revoke and regenerate the token in Roku Ads Manager, and then update the credential in Amperity.
	Roku settings Event group ID Required The Roku event group (online property) that receives the events. Find it in Roku Ads Manager under Events. A destination sends to a single event group. Important The CAPI token must belong to the same Roku Ads account as the event group. A token from a different account authenticates but is not authorized for the event group.
	Request properties A query must return event_name, event_source, event_time, and email. All other columns are optional. See Conversions API parameters for the full list, and Supported event types and sources for the allowed event_name and event_source values.

Configure credentials

Configure credentials for Roku before adding a destination.

An individual with access to Roku should use SnapPass to securely share “CAPI token” details with the individual who configures Amperity.

To configure credentials for Roku CAPI

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Roku CAPI. Note Amperity provides two Roku connectors. Select Roku CAPI to send conversion events to the Roku Conversions API. Roku Audience is a separate connector that sends first-party audiences for household targeting. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “roku-capi” credential type, configure settings, and then click Save. CAPI token Required A bearer token (JWT) that authorizes Amperity to send events to the Roku Conversions API. Generate the token in Roku Ads Manager under Events > CAPI. Generating a token requires the Admin or Org Admin role. The token does not expire but can be revoked; to rotate it, revoke and regenerate the token in Roku Ads Manager, and then update the credential in Amperity.

Add destination

Use a sandbox to configure a destination for Roku. Before promoting your changes, send a sample audience, and then verify the results in Roku. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination

	Open the Destinations tab to configure a destination for Roku. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Roku events” and “Send conversion events to Roku.”.
	Credentials allow Amperity to connect to Roku. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Event group ID Required The Roku event group (online property) that receives the events. Find it in Roku Ads Manager under Events. A destination sends to a single event group.
	After configuring this destination users may use orchestrations to send query results Roku.
	Validate the audience with Roku by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Roku. Send the sample audience to Roku and verify the sample audience is correct in Roku. Make adjustments if necessary. Only send full audiences after validation is complete.

Build a query

Use a query to build a combination of data — typically from the Unified Transactions and Customer 360 tables — that returns one row per conversion event to send to Roku. Each row must include an event type, an event source, an event timestamp, and a customer email. Adding a phone number can improve the match rate; you can also include additional identifiers — name, gender, and birthdate — and event attributes such as conversion value, currency, and order ID, which Amperity sends with each event.

Review the Conversions API parameters section for the columns your query must and may return, and the Supported event types and sources section for the allowed event_name and event_source values.

Bound the query to recent events so each orchestration sends new conversions instead of re-sending the full transaction history; choose a window that matches how often the orchestration runs. A query that returns a collection of recent purchase events for use in Roku is similar to:

SELECT
  'PURCHASE' AS event_name
  ,'website' AS event_source
  ,ut.order_datetime AS event_time
  ,c360.email AS email
  ,c360.phone AS phone
  ,c360.country AS country
  ,c360.given_name AS given_name
  ,c360.surname AS surname
  ,ut.order_id AS event_id
  ,ut.order_revenue AS value
  ,ut.currency AS currency
  ,ut.order_id AS order_id
FROM Unified_Transactions ut
LEFT JOIN Customer_360 c360 ON ut.amperity_id = c360.amperity_id
WHERE ut.order_datetime > (CURRENT_DATE - interval '7' day)
AND c360.email IS NOT NULL

Supported event types and sources

event_name and event_source are required and must exactly match one of the values below. The values are case-sensitive: event_name values are uppercase and event_source values are lowercase, so Purchase or Website are rejected. Rows with a missing or unrecognized event_name or event_source are not sent and are reported as failed.

Supported event_name values (27)

ACHIEVE_LEVEL, ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, APP_INSTALL, COMPLETE_REGISTRATION, CONTACT, CUSTOMIZE_PRODUCT, DONATE, DOWNLOAD, FIND_LOCATION, FIRST_VIDEO_VIEW, INITIATE_CHECKOUT, LEAD, PAGE_VIEW, PURCHASE, QSS, SCHEDULE, SEARCH, SESSION_START, SIGN_UP, START_TRIAL, SUBSCRIBE, SUBSCRIPTION_CANCELLATION, SUBSCRIPTION_RENEWAL, UNLOCK_ACHIEVEMENT, VIEW_CONTENT

Supported event_source values (10)

chat, ctv_app, email, mobile_app, phone_call, physical_store, roku, system-generated, website, other

Data validation

Amperity validates each row before sending and drops rows that Roku would reject, so that one invalid row does not cause an entire batch of events to be rejected. Dropped rows are reported as failed with the reason. A row is dropped when:

• event_name, event_source, or event_time is missing or unrecognized.

• email is missing or is not a valid email address (email is the required identifier).

• event_time is more than one hour in the future — usually a sign of a wrong column mapping or a milliseconds-versus-seconds mismatch.

Optional fields that cannot be used — for example, an unparseable birthdate, a non-US national-format phone number sent without a country, or a non-numeric value — are dropped from that row individually and reported; the rest of the event is still sent.

Conversions API parameters

The following table describes each column Amperity sends to Roku. A query must return columns with the same name as listed in the “Amperity name” column; Amperity maps them to the Roku parameter names automatically.

Important

A query must return event_name, event_source, event_time, and email. All other columns are optional.

Amperity name	Roku parameter	Description
event_name	event_name	Required The type of conversion event. Must be one of the 27 supported values (see Supported event types and sources).
event_source	event_source	Required Where the event originated. Must be one of the 10 supported values (see Supported event types and sources).
event_time	event_time	Required When the event occurred. Accepts a UNIX epoch-seconds value, a date- or time-typed column, or a string in full ISO 8601 instant form with a UTC offset (for example, 2026-07-10T12:00:00Z). A date-only string such as 2026-07-10, or a space-separated timestamp such as 2026-07-10 12:00:00, is not accepted as a string — send those from a date- or time-typed column instead. Timestamps more than one hour in the future are rejected.
email	em	Required An email address. Note em is part of the user_data object. Amperity strips plus-addressing (john+promo@example.com is treated as john@example.com) and applies SHA-256 hashing before sending.
phone	ph	Optional A phone number. Amperity normalizes the number to E.164 format (including the leading +) and applies SHA-256 hashing before sending. Note For national-format numbers, include a country column so Amperity can parse them; without it, non-US national-format numbers are dropped. Numbers already in E.164 format parse without a country.
country	Not sent	Optional A country used only to normalize national-format phone numbers. It is not sent to Roku. Parsing defaults to US when country is absent.
given_name	fn	Optional A first name. Amperity applies SHA-256 hashing before sending.
surname	ln	Optional A last name. Amperity applies SHA-256 hashing before sending.
gender	ge	Optional A gender identifier. Amperity maps values to male, female, or unknown (unrecognized values become unknown) and applies SHA-256 hashing before sending.
birthdate	db	Optional A birthdate. Amperity normalizes it to yyyy-mm-dd and applies SHA-256 hashing before sending. Values that cannot be parsed as a date are dropped from the row.
event_id	event_id	Optional A unique identifier for the event, passed through as-is. Roku uses it to deduplicate events. Provide a stable value (for example, an order ID) so that repeated sends of the same event are not double-counted.
value	value	Optional A numeric conversion value for the event. Part of the custom_data object.
currency	currency	Optional The currency for value, as a three-character ISO 4217 code. Part of the custom_data object.
order_id	order_id	Optional The order identifier associated with the event. Part of the custom_data object.
purchase_type	purchase_type	Optional A purchase type for the event. Part of the custom_data object.

Workflow actions

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

	You may receive a notifications error for a configured Roku destination. This appears as an alert in the notifications pane on the Destinations tab. If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page.
	On the Workflows page, review the individual steps to determine which steps have errors that require your attention, and then click Show Resolutions to review the list of workflow actions generated for this error.
	A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Roku, including: Invalid credentials Invalid settings
	Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Note

If Roku rejects an entire batch of events, the workflow reports the error with Roku’s field-level detail — review the event field values returned by your query. If sends are rate limited, Amperity retries automatically; reduce the volume of events sent per orchestration if the limit persists.

Invalid credentials

The credentials that are defined in Amperity are invalid.

To resolve this error, verify that the credentials required by this workflow are valid.

1. Open the Credentials page.

2. Review the details for the credentials used with this workflow. Update the credentials for Roku if required.

3. Return to the workflow action, and then click Resolve to retry this workflow.

Invalid settings

The configuration for this workflow has a setting that Roku was unable to accept. This most often means the CAPI token is not authorized for the configured event group — verify that the Event group ID is correct and that the CAPI token belongs to the same Roku Ads account as the event group.

To resolve this error, verify the settings configured for this workflow in Amperity.

1. Open the Destinations page and review the settings for the Roku destination associated with this workflow. Verify the Event group ID, and that the connected credential’s CAPI token was generated in the same Roku Ads account.

2. Return to the workflow action, and then click Resolve to retry this workflow.