Target your advertising activity at specific audiences to increase its effectiveness. You can choose from standard audiences, curated and provided by Roku, and your own custom audiences, which you create. You can create custom audiences via customer lists (first-party data) or based on events (specific user actions). If you want to use standard audiences instead of creating your own custom audiences, see About standard audiences. These are the two types of customer audiences you can create, and how they differ:

• Customer list audience

  Create a customer list audience with your first-party data. Upload a file containing customer contact information which Roku matches to its users to create a specific group you can target. Some common uses for a customer list audience include reengaging past buyers and promoting loyalty programs.

• Event-based audience

  Create an event-based audience based on specific actions (events) that people take on your website, app, and offline, tracked by either a JavaScript pixel or Conversions API (CAPI). Examples of events are: viewing a specific product page (page views), adding an item to a shopping cart (add to cart), or completing a registration (complete registration). Some common uses for event-based audiences include:

  • Retargeting customers who visited or took an action on your website to convert potential customers or drive existing customers to buy again.
  • Removing customers who recently completed a specific action to hone your targeting and reduce waste.

Use the same POST Create custom audiences call to create either type of custom audience. Both processes are explained, below.

Create a custom audience from a customer list

Your customer list needs to be in the form of a CSV (.csv) or TXT (.txt) file and is referred to in Ads API as a customer relationship management (CRM) file. If you aren’t sure how to properly format your CRM file, see CRM file rules and formatting below.

1. Make a POST Create CRM file upload URLs call and include the following in your request body parameters:

   • filename- name of your CRM file
   • account_uid - the unique identifier of your account

   A successful call returns three things:

   • An upload_url- the unique, write-only URL you upload your CRM file to in Step 2. You need one upload_url per CRM file, or custom audience that you want to create.
   • A metadata_url you can use to validate the upload of Step 2 is successful, if you want.
   • The raw_path you use in Step 3.

2. Make a PUT call to the upload_url you received in Step 1 with your CRM file.

3. Make a POST Create CRM file objects call to inform Ads API that you've uploaded your CRM file. Include the following in your request body parameters:

   • filename - name of your CRM file (has to match the filename in Step 1)
   • account_uid - unique identifier of your account
   • raw_path - the path to the raw CRM file

   A successful call returns the crm_file_uid you need in Step 4 along with data like input_size_counts, matched_size_counts, and household_matched_counts with a value of zero. This is because the data ingestion hasn't been triggered yet.

4. Optionally, to check the processing status of your CRM file, make a GET Get a CRM file call. Check the successful response for status: match_valid. If you don't see this, the two most common errors to check are:

   • The headers in your file could be formatted incorrectly.
   • The data in your file didn't match to 1,000 Roku households.

5. Make a POST Create custom audiences call and include the following in your request body parameters:

   • name - the name of the custom audience
   • account_uid - the unique identifier of your account
   • audiences_config - the configuration for how users are added to this audience. type set to file_audiences, needs to include the following key-value pairs:
     • crm_file_uid - the unique identifier of your CRM file
     • expiration_value - the expiration value of your CRM file key. Default is 90.
     • expiration_unit - the expiration unit of your CRM file key. Default is day.

You can make a GET Get an audience call to view your newly created custom audience.

CRM file rules and formatting

Your CRM file should include as much of the following information as possible to improve your data matching: customer email, SHA-256-hashed email address, phone number, mobile advertiser ID (MAID) or IP address.

It needs to follow these rules:

• Must be in the form of a CSV (.csv) or TXT (.txt) file
• Must include enough data to match at least 1,000 Roku households
• hashed email addresses can’t be Base64-encoded

See the table below for an example of a customer list in the form of a CSV file.

Create a custom audience using events data

Make a POST Create custom audiences call and include the following in your request body parameters:

• name - the name of the custom audience
• account_uid - the unique identifier of your account
• audiences_config - the configuration for how users are added to this audience. type set to event_audiences, provide the following keys and a value for each:
  • event_name - the name of the event you want to use for your audience (see the full list of events, below)
  • event_group_uid - the unique identifier of the event group
  • qualified_event_timeframe_value - the value of your qualified_event_timeframe_unit. Max is 90.
  • qualified_event_timeframe_unit - the unit of your qualified_event_timeframe. Default is days.

You can make a GET Get an audience call to view the newly created custom audience.

Events

The table below lists the possible events with descriptions.

Custom audience status

Custom audience objects returned by the API don't include a status field. Their status is only visible in the Roku Ads Manager UI. For event-based audiences, the UI reflects a PENDING state for 72 hours after audience creation before moving to ACTIVE. You can’t forecast with an audience while it’s PENDING. For file-based audiences, status can be: PENDING, ACTIVE, and EXPIRED.