Skip to main content

Custom Audience Import API

Our data management platform provides the ability for Rokt to receive custom audience data at any frequency you prefer. If you’re working with Rokt as an advertiser, these lists can be used in your campaigns to either target or suppress certain customers from seeing your offers. If you’re working with Rokt as a partner, these lists can be used to determine which customers see the Rokt experience on your site.

A common method of delivering custom audience data to Rokt is through the use of an API.

We recommend batching your requests (up to 1 million contacts per request) before sending them to Rokt. You can do this multiple times in a single day (or at any frequency you prefer).

Endpoint

Endpoint URLhttps://data.rokt.com/api/1.0/import/suppression

The API accepts a JSON payload. You must set the Content-Type header to application/json.

Authorization

The API expects an authorization header as part of the request. This is to ensure that you have the right permissions to send data to your account in the Rokt platform. The authorization header value should be your account's unqiue API key. Reach out to your account manager to obtain this value.

Parameters

Exactly one of the following keys must be present in the request body.

If using hashed email, ensure that you first remove any whitespace and lowercase the email address before hashing.

ParameterDescription
emailA single email address
emailsAn array of email address
sha256A single SHA-256 hashed email
sha256sAn array of SHA-256 hashed emails

Additional parameters include:

ParameterTypeDescriptionExample
actionRequiredUse include if you want to add someone to the specified list.
Use exclude if you want to remove someone from the specified list.
include
exclude
listOptionalThe name of the custom audience list to use.
If no list value is provided, the email addresses will be imported into the AdvertiserDatabase list by default.
US_Customers

Limits

TypeLimit
Request size1000 emails per 1 request.
Rate limit1 per second.
Concurrency limit1
note

The limits above are recommended for this API. Larger amounts may be successful, however are not recommended.

Response handling

HTTP status codeBodyDescription
201CreatedThe email(s) were successfully added to or removed from the custom audience list.
400Bad RequestYou receive a 400 Bad Request if there are missing required fields, or your request is sent in the wrong format.

Command line examples

On a Linux or Mac OS X system with the curl command installed, the following command performs an import of the email addresses alice@example.com and bob@example.com, assuming that the API_KEY environment variable is set to your API key:

cURL

curl https://data.rokt.com/api/1.0/import/suppression --header "Authorization: $API_KEY" --header "Content-Type: application/json" --data '{"emails":["alice@example.com","bob@example.com"],"action":"include"}'

The following command would import the single SHA256 hash "1753bdb368271a785887ddbfb926164f2f7c6a88f609c07ff0401c5572955206" into a custom audience list called US_Customers. This string is the SHA256 hash of hello@example.com (since we expect hashes to be of lowercase email addresses, this is the hash we would look for to determine whether the email address HELLO@EXAMPLE.COM is in the custom audience list):

cURL

curl https://data.rokt.com/api/1.0/import/suppression --header "Authorization: $API_KEY" --header "Content-Type: application/json" --data '{"list":"US_Customers","sha256":"1753bdb368271a785887ddbfb926164f2f7c6a88f609c07ff0401c5572955206","action":"exclude"}'

Testing

Note that the above examples point to our live production system. So if you test with email addresses like alice@example.com then, in addition to your real customers, we would consider alice@example.com to be a member of your custom audience list in Rokt. If you use this list for exclusion targeting, for example, we would not show the Rokt widget to anyone who entered alice@example.com as their email address.

Was this article helpful?