Target your advertising activity at specific audiences to increase its effectiveness. You can choose from audiences curated by Roku, and you can create your own custom audiences. There are two ways you can create a custom audience: from a customer list and from events data. Currently with the Ads API, you can only create a custom audience from a customer list.

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.
     The audiences_config attribute 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. If you have user access to the ad account to which it belongs, you can also view this custom audience in the Custom audience library in the Ads Manager UI.

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 address can't be Base64-encoded

Example of a customer list in the form of a CSV file