Roku Advertising Direct
Upload custom audience segments to Roku for connected TV (CTV) advertising targeting. Zeotap syncs your warehouse audiences directly to the Roku Ads platform for precise CTV campaign targeting.
Beta API notice: The Roku Ads API is currently in public beta. Some endpoints and behaviors may change. Contact Roku Ads support to confirm partner access and the current audience management contract for your ad account.
Prerequisites
- A Roku Ads Manager account with API access
- An ad account ID from Roku Ads Manager
- OAuth 2.0 credentials (client ID and client secret) or a valid access token
- Admin role in your Roku Ads Manager organization for OAuth app setup
Permissions
Your Roku Ads API credentials must have access to the Audiences scope to create and manage custom audiences.
Authentication
Roku Advertising Direct supports two authentication methods.
OAuth 2.0 (Recommended)
- Log in to Roku Ads Manager as an admin
- Navigate to Settings and register a new application
- Save the Client ID, Client Secret, and Authorization URL
- In Zeotap, select OAuth 2.0 as the authentication method
- Enter your Client ID and Client Secret
- Click Authorize to complete the OAuth flow and grant access to your ad accounts
Bearer Token
- Obtain an access token from the Roku Ads API
- In Zeotap, select Bearer Token as the authentication method
- Enter your Access Token
Note: Bearer tokens expire after 24 hours. For production use, OAuth 2.0 with automatic token refresh is recommended.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Ad Account ID | Text | Yes | Your Roku Ads ad account ID. Found in Roku Ads Manager under account settings. |
| API URL | Text | No | Roku Ads API base URL. Default: https://ads.api.roku.com/v1. Override only for testing. |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Audience Name | Text | Yes | Name for the custom audience. If no Audience ID is provided, a new audience with this name is created. |
| Audience ID | Text | No | Existing audience ID. Leave blank to create a new audience automatically. |
| Identifier Type | Select | Yes | Type of identifier for audience matching: Email (SHA256), Phone (SHA256), Mobile Ad ID (MAID), or IP Address. Default: Email (SHA256). |
Supported Operations
Sync Modes
This is an audience-only destination. Standard data sync modes are not applicable.
Audience Sync Modes
| Mode | Supported | Description |
|---|---|---|
| Add | Yes | Add identifiers to the audience |
| Upsert | Yes | Add identifiers idempotently (same as Add for audience membership) |
The Roku Ads API exposes customer-list ingestion as an additive, match-based operation. There is no publicly documented per-member remove endpoint, so Remove and Mirror modes are not supported. To refresh audience membership, rotate to a new audience or clear the audience from Roku Ads Manager before re-syncing.
Features
- Field Mapping: No
- Schema Introspection: No
Required Mapping Fields
Depending on the Identifier Type selected:
| Identifier Type | Required Field | Description |
|---|---|---|
| Email (SHA256) | email | Email address (automatically normalized and SHA256-hashed) |
| Phone (SHA256) | phone | Phone number (automatically normalized to E.164 and SHA256-hashed) |
| Mobile Ad ID | maid or external_id | Mobile advertising identifier (IDFA or GAID) |
| IP Address | ip_address | IPv4 or IPv6 address |
Default Destination Fields
No default destination fields. Roku custom audiences are identifier-based and do not accept additional attributes.
How It Works
- Authentication: Zeotap authenticates with the Roku Ads API using your OAuth credentials or access token
- Audience Creation: If no existing audience ID is provided, Zeotap creates a new custom audience in your Roku Ads account. It first checks for an existing audience with the same name to avoid duplicates.
- Identifier Processing: Depending on the identifier type, values are normalized and hashed:
- Emails are lowercased, trimmed, and SHA256-hashed
- Phone numbers are normalized to E.164 format and SHA256-hashed
- MAIDs and IP addresses are sent as-is
- Batch Upload: Identifiers are uploaded in batches of up to 10,000 per request. Uploads are additive — Roku matches the supplied identifiers against Roku households and appends them to the custom audience.
Rate Limits
The Roku Ads API enforces rate limits per ad account. Zeotap uploads data in batches of up to 10,000 identifiers per request and processes batches sequentially to stay within limits. If you experience throttling, consider reducing sync frequency.
Best Practices
- Use OAuth 2.0 for production syncs to avoid manual token rotation
- Choose the right identifier type based on your data quality. Email typically provides the best match rates for CTV targeting.
- Minimum audience size: Roku requires at least 1,000 matched households before a custom audience can be used for targeting
- Processing time: Customer list audiences may take up to one hour to process after upload
- Avoid duplicate audiences: If you provide an audience name without an ID, Zeotap searches for existing audiences with the same name before creating a new one
- Rotate audiences for lifecycle campaigns: Because Roku’s custom audiences are additive, use a fresh audience per campaign cohort rather than trying to shrink membership in place
Troubleshooting
Authentication failed: invalid or expired access token
Bearer tokens expire after 24 hours. Switch to OAuth 2.0 authentication for automatic token refresh, or regenerate your access token in Roku Ads Manager.
Audience not available for targeting
Custom audiences require at least 1,000 matched Roku households. Check your audience size in Roku Ads Manager. Also, new audiences may take up to one hour to process before becoming available.
Rate limiting errors
If you see rate-limit errors, reduce your sync frequency or contact Roku support to discuss higher rate limits for your account.
Identifiers not matching
Ensure you are using the correct identifier type. Email and phone identifiers are automatically normalized and hashed by Zeotap. For MAID identifiers, ensure values are valid IDFA (iOS) or GAID (Android) formats.
Audience membership not shrinking
Roku’s custom-audience API is additive — there is no supported per-member remove operation. To reduce or reset an audience, clear or delete the audience from Roku Ads Manager and re-sync, or create a new audience and point new campaigns at it.
OAuth authorization error
Ensure your Roku Ads Manager account has admin permissions. The OAuth app must be registered with the correct redirect URI matching your Zeotap instance.