Send conversion events to 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.

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.

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

Add orchestration

An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.

To add an orchestration

1. Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.

2. From the Object type dropdown, select Query.

3. From the Object dropdown, select the query for which results is sent to Roku.

4. From the Destination dropdown, select a destination that is configured for sending data to Roku.

5. Verify all settings.

6. Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.

7. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

To run the orchestration

1. Open the Activations page, select the Orchestrations tab, and then open the menu for the Roku orchestration. Select Run.

2. The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.

3. When the orchestration has run successfully, the status is updated to “Completed”.

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.