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 before sending them to Rokt. You can do this multiple times in a single day (or at any frequency you prefer).
Endpoint
| Endpoint URL | https://data.rokt.com/v3/import/suppression |
|---|
The API accepts a JSON payload. You must set the Content-Type header to application/json.
Authentication
Note: Currently in Public Beta
Reach out to your Rokt account manager to create a public and secret key pair for the accounts that you would like to submit conversion events. These keys you receive will be:
| Name | Value |
|---|---|
| Rokt Public Key | rpub-*****-* |
| Rokt Secret Key | rsec-*****-* |
Request Body
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.
| Parameter | Description |
|---|---|
| A single email address | |
| emails | An array of email address |
| sha256 | A single SHA-256 hashed email |
| sha256s | An array of SHA-256 hashed emails |
Additional parameters include:
| Parameter | Type | Description | Example |
|---|---|---|---|
| accountId | Required | Rokt Account ID as seen in OnePlatform. | 123456789 |
| action | Required | Use include if you want to add someone to the specified list which could then be used for either targeting or suppression. Use exclude if you want to remove someone from the specified list. | include exclude |
| list | Optional | The 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
| Type | Limit |
|---|---|
| Request size | 100,000 emails per 1 request. |
| Rate limit | 4 per second. |
| Concurrency limit | 4 |
The limits above are recommended for this API. Larger amounts may be successful, however are not recommended.
Response handling
| HTTP status code | Body | Description |
|---|---|---|
| 201 | Created | The email(s) were successfully added to or removed from the custom audience list. |
| 400 | Bad Request | You 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 -X POST https://data.rokt.com/v3/import/suppression \
--header "Authorization: Basic base64(rpub-*:rsec-*)" \
--header "Content-Type: application/json" \
--data '{"accountId": "REPLACE_ME", "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 -X POST https://data.rokt.com/v3/import/suppression \
--header "Authorization: Basic base64(rpub-*:rsec-*)" \
--header "Content-Type: application/json" \
--data '{"accountId": "REPLACE_ME", "list":"US_Customers","sha256":"1753bdb368271a785887ddbfb926164f2f7c6a88f609c07ff0401c5572955206","action":"exclude"}'
Authentication (Legacy)
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 if still using the legacy API.
Endpoint (Legacy)
| Endpoint URL | https://data.rokt.com/api/1.0/import/suppression |
|---|
The API accepts a JSON payload. You must set the Content-Type header to application/json. The request body, API limits and response handling are exactly the same as POST /v3/import/suppression API.
Command Line Examples (Legacy)
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 -X POST 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 -X POST 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.