Audience API Integration Guide

The Rokt Audience API enables advertisers and technology partners to forward their audience segments directly to Rokt for use in campaign targeting and suppression. By keeping your audiences in sync, you can ensure your campaigns reach the right users, avoid serving ads to those who shouldn't see them, and reduce wasted spend — all of which drive better overall campaign performance.

Prerequisites

Before you begin, ensure you have:

• API credentials – Contact your Rokt account manager to request an API key and secret pair. These credentials are used for Basic Authentication with all API requests.

---

Authentication

The Rokt Audience API can be authenticated with basic authentication in either of two ways:

Using your HTTP client's authentication settings

If your HTTP client supports basic authentication, use your API key for "username" and your secret for "password".

Setting the Authorization header manually

If your HTTP client doesn't handle authentication automatically, construct the header yourself:

1. Concatenate your key and secret together using a colon (:) separating the two:

   example-api-key:example-api-secret

2. Base64 encode the result with UTF-8:

   ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

3. Prefix the encoded string with the authorization method, including a space:

   Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

4. Set the resulting string as the Authorization header in your HTTP requests:

   Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

Required Headers

Header	Value	Description
Content-Type	application/json	Request body format
Charset	utf-8	Character encoding
Authorization	Basic base64(api-key:api-secret)	Authentication credentials

---

API Reference

Endpoint

POST https://inbound.mparticle.com/s2s/v1/UserProfile

Request Body Structure

The request body is an array of objects, where each object represents a single user and contains the fields needed to identify them in identities and device_updates, add attributes to their profile in user_attributes, and add or remove them from one or more audiences using the external_audience_membership_updates object.

To include multiple users in a single payload, add additional objects to the array. The request_type for each object must always be set to "user_profile_modify".

Each payload can include up to 100 users.

[
  {
    "request_type": "user_profile_modify",
    "environment": "production",
    "data": {
      "source_request_id": "unique-request-id-here",
      "identities": {
        "customerid": "cust_123456",
        "email": "email@example.com",
        "other": "SHA256-email"
      },
      "device_updates": [
        {
          "device_info": {
            "ios_advertising_id": "00000000-0000-0000-0000-000000000000"
          }
        }
      ],
      "user_attributes": {
        "workspace": [
          {
            "attribute_name": "some_attr_1",
            "attribute_value": "some_val_1"
          },
          {
            "attribute_name": "some_attr_2",
            "attribute_value": "some_val_2"
          }
        ]
      },
      "external_audience_membership_updates": [
        {
          "external_audience_id": "audience_name_1",
          "action": "add",
          "change_timestamp_ms": 1713895200000
        },
        {
          "external_audience_id": "audience_name_2",
          "action": "remove",
          "change_timestamp_ms": 1713895200000
        }
      ]
    }
  }
]

The Audience API supports up to 100 users per request.

[
  { "request_type": "user_profile_modify", ... },
  { "request_type": "user_profile_modify", ... },
  { "request_type": "user_profile_modify", ... }
]

---

Field Reference

General Request Body Fields

These fields are set at the root level of each user object.

{
  "request_type": "user_profile_modify",
  "environment": "production",
  "data": {
    "source_request_id": "unique-request-id-here"
  }
}

Field	Type	Required	Description
request_type	string	Yes	Must be set to "user_profile_modify".
environment	string	Yes	Must be set to "production".
source_request_id	string	No	A value to uniquely identify this request. Any valid string is accepted.

User Identities

User identities are set in the data.identities object. At least one identifier is required for Rokt to match the request to a user.

"identities": {
  "email": "email@example.com",
  "other": "SHA256-hashed-email",
  "customerid": "cust_123456"
}

Field	Type	Required	Description
email	string	Conditionally required	Plain text email address. Must be lowercase and trimmed. Required if hashed email is not provided.
other	string	Conditionally required	SHA-256 hashed email. Ensure it is lowercase and trimmed before hashing. Required if plain text email is not provided.
customerid	string	No	Internal customer or user ID.

Device Information

Device identifiers are sent as objects in the data.device_updates[] array and improve match rates, especially for mobile users.

"device_updates": [
  {
    "device_info": {
      "ios_advertising_id": "00000000-0000-0000-0000-000000000000"
    }
  }
]

Field	Type	Required	Description
ios_advertising_id	string	No	Apple iOS device advertising identifier (IDFA).
android_advertising_id	string	No	Google Android advertising identifier (GAID).
ios_idfv	string	No	Apple iOS device identifier (IDFV).
android_uuid	string	No	Android identifier.

User Attributes

Each attribute is sent as an object in the data.user_attributes.workspace[] array. Set attribute_name to the attribute you want to send and attribute_value to the corresponding value.

"user_attributes": {
  "workspace": [
    {
      "attribute_name": "firstname",
      "attribute_value": "Jane"
    },
    {
      "attribute_name": "lastname",
      "attribute_value": "Smith"
    }
  ]
}

Rokt recommends sending as many of the following user attributes as possible to improve attribution, reporting, and optimization.

Attribute	Type	Required	Description
firstname	string	No	The customer's first name.
firstnamesha256	string	No	SHA-256 hash of first name. Prior to hashing, lowercase and trim all trailing spaces.
lastname	string	No	The customer's last name.
lastnamesha256	string	No	SHA-256 hash of last name. Prior to hashing, lowercase and trim all trailing spaces.
mobile	string	No	Phone numbers can be formatted either as 1112345678 or +1 (222) 345-6789.
mobilesha256	string	No	SHA-256 hash of mobile number. Mobile number must be formatted as 5551234567 (no dashes or spaces) prior to hashing.
age	string	No	The customer's age.
dob	string	No	Date of birth. Formatted as yyyymmdd.
gender	string	No	The customer's gender. For example, M, Male, F, or Female.
city	string	No	The customer's city.
state	string	No	The customer's state.
zip	string	No	The customer's zip code.
title	string	No	The customer's title. For example, Mr, Mrs, Ms.

Data Normalization for Hashing

Before hashing any value with SHA-256:

• Lowercase all text
• Trim leading and trailing whitespace
• Normalize phone numbers to format 5551234567 (remove dashes, spaces, parentheses, and country code)

Audience Membership Updates

Each audience update is sent as an object in the data.external_audience_membership_updates[] array. Add one object per audience.

"external_audience_membership_updates": [
  {
    "external_audience_id": "premium_users",
    "action": "add",
    "change_timestamp_ms": 1713895200000
  },
  {
    "external_audience_id": "retargeting_list",
    "action": "remove",
    "change_timestamp_ms": 1713895200000
  }
]

Field	Type	Required	Description
external_audience_id	string	Yes	Name of the audience.
action	string	Yes	Accepted values: "add" or "remove". Use "add" to include the user in the audience, or "remove" to exclude them.
change_timestamp_ms	number	No	Unix timestamp of the audience membership change (in milliseconds).

Batching audience updates

Where possible, batch all audience updates for a single user into one request. This improves internal processing performance and reduces overhead. Add one object per audience to the external_audience_membership_updates array.

---

Limits

• Each advertiser account is limited to 1,000 unique audiences. Reach out to your Account Manager if this limit is exceeded.
• You can send up to 100 request bodies, each representing a unique user, in a single request.
• The external_audience_id value is limited to 100 characters.

---

Error Responses

Status	Code	Description
202	Accepted	The request was accepted. Note that a 202 does not guarantee successful processing and errors may still occur downstream. Contact your Account Manager to confirm your audience is live in Rokt.
400	Bad Request	The request JSON is malformed, there are no valid UserProfileRequests after validation, or the payload is too large. The API supports 100 requests per payload.
401	Unauthorized	The authentication header is missing.
403	Forbidden	The authentication header is present, but invalid.
429	Too Many Requests	The API uses an acceleration-based rate limit, starting at 270 requests per second, that scales up automatically over time. If you exceed the current limit, the API returns a 429 Too Many Requests response. We recommend retrying with exponential backoff and random jitter if no Retry-After header is present.
503	Service Unavailable	We recommend retrying your request in an exponential backoff pattern.
5xx	Internal Server Error	A server-side error has occurred, please try your request again. If this error persists, reach out to your Account Manager.

Example response body for an unsuccessful request

{
    "errors" :
    [
        {
            "code" : "BAD_REQUEST",
            "message" : "requests[0].data.external_audience_membership_updates[0].external_audience_id cannot be longer than 100 characters."
        }
    ]
}