Event and Audience API Integration Guide

The Rokt Event API enables advertisers to send conversion and audience data from your server directly to Rokt. This server-to-server integration provides reliable, comprehensive conversion tracking that isn't affected by browser limitations or ad blockers.

Overview

What is the Event API?

The Event API is a server-side integration that allows you to:

• Send conversion events - Report purchases, sign-ups, and other conversion actions to Rokt for campaign optimization and attribution
• Sync audience data - Upload user segments for targeting or suppression in your Rokt campaigns

Why use a server-side integration?

Benefit	Description
Reliability	Not affected by ad blockers, browser privacy settings, or cookie restrictions
Coverage	Track conversions across all channels—web, mobile app, in-store, call center
Data quality	Send richer, more accurate data directly from your backend systems
Real-time	Events are processed in near real-time for faster optimization

---

Prerequisites

Before you begin, ensure you have:

1. API credentials - An API key and API secret from your Rokt account manager
2. Rokt Click ID (optional, for attributed conversions) - Captured from Rokt ad interactions

Obtaining API Credentials

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

Capturing the Rokt Click ID (Optional but Recommended)

Capturing the Rokt Click ID is optional but highly recommended. When included as passbackconversiontrackingid in your API requests, this ID significantly improves the ability to match a click to the user who converted.

Rokt can still perform attribution without the Click ID, but including it results in more accurate matching.

---

Quick Start

Here's an example of sending a conversion event:

curl -X POST https://s2s.us2.mparticle.com/v2/events \
  --user "YOUR_API_KEY:YOUR_API_SECRET" \
  --header "Content-Type: application/json" \
  --header "Charset: utf-8" \
  --data '{
    "environment": "development",
    "ip": "172.3.51.182",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890"
    },
    "events": [
      {
        "event_type": "custom_event",
        "data": {
          "event_name": "conversion",
          "custom_attributes": {
            "amount": 100.00,
            "currency": "USD",
            "quantity": 1,
            "conversiontype": "purchase",
            "productname": "Maroon 5 t-shirt, Warriors vs. Raptors",
            "sku": "230847",
            "paymenttype": "VISA",
            "margin": 10.0,
            "transactionid": "ABC789",
            "confirmationref": "XYZ123"
          }
        }
      }
    ]
  }'

A successful request returns HTTP 202 Accepted.

---

Authentication

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

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

2. You can manually set the Authorization header by including your key and secret encoded together:

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

   example-api-key:example-api-secret

   2.2. Base64 encode the result with UTF-8:

   ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

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

   Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

   2.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://s2s.us2.mparticle.com/v2/events

Request Body Structure

{
  "environment": "production",
  "ip": "203.0.113.42",
  "device_info": { ... },
  "user_attributes": { ... },
  "user_identities": { ... },
  "integration_attributes": { ... },
  "events": [ ... ]
}

---

Field Reference

Root Level Fields

Field	Type	Required	Description
environment	string	Yes	Must always be "production", even when testing.
ip	string	No	User's IP address. Used for geolocation and fraud detection.

User Identities (Required)

At least one user identifier is required for Rokt to match the event to a user.

Field	Type	Required	Description
user_identities.email	string	Conditional	Plain text email address. Must be lowercase and trimmed. Required if other is not provided.
user_identities.other	string	Conditional	Alternative identifier (e.g., SHA256 hashed email). Required if email is not provided.

Email Format

Send plain text email in the email field, or SHA-256 hashed email in the other field. If sending a hashed email, ensure it is lowercase and trimmed before hashing.

Device Information

Device identifiers improve match rates, especially for mobile users.

Field	Type	Required	Description
device_info.http_header_user_agent	string	No	Browser or device user agent string.
device_info.ios_advertising_id	string	No	iOS IDFA (Identifier for Advertisers). Format: UUID.
device_info.android_advertising_id	string	No	Android Advertising ID (AAID). Format: UUID.

User Attributes

User attributes provide additional data for matching and personalization. Rokt recommends setting as many of the following user attributes as possible:

Field	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.
language	string	No	Language associated with the purchase.
value	string	No	The value of the customer.
predictedltv	string	No	The total predicted lifetime value of the customer.

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)

Integration Attributes

Field	Type	Required	Description
integration_attributes.1277.passbackconversiontrackingid	string	No	The Rokt Click ID. Links this conversion to a specific Rokt ad interaction for attribution.

Attribution

Rokt can perform attribution with or without the passbackconversiontrackingid. However, including the Click ID significantly improves the ability to match a click to the user who converted, resulting in more accurate attribution.

Events Array

The events array contains the conversion data.

When to include the Events Array

The events array is required when sending conversion events. If you are only sending audience data, you can omit the events array entirely.

Field	Type	Required	Description
events	array	Yes	Array of event objects. Must contain at least one event.
events[].event_type	string	Yes	Must be "custom_event".
events[].data.event_name	string	Yes	Must be "conversion".
events[].data.custom_event_type	string	Yes	Must be "transaction".
events[].data.timestamp_unixtime_ms	number	Yes	When the conversion occurred, in milliseconds since Unix epoch.
events[].data.custom_attributes.conversiontype	string	Yes	The type of action the user performed (e.g., "purchase", "signup", "subscription"). Used with confirmationref for deduplication.
events[].data.custom_attributes.confirmationref	string	No	Order or confirmation number. Used with conversiontype to deduplicate events.
events[].data.custom_attributes.amount	string	No	Transaction value as a string (e.g., "99.99").
events[].data.custom_attributes.currency	string	No	ISO 4217 currency code (e.g., "USD", "EUR", "GBP").

---

Audience Data

To send audience segment data (for targeting or suppression), add audience attributes to user_attributes.

When to send Audience Data

When sending audience data only, you only need to include the user_identities and user_attributes objects. The events array is not required for audience-only requests.

Naming convention: All audience attributes must be prefixed with audience_. Include one attribute for each audience you want to send to Rokt.

Field	Type	Required	Description
audience_{audience_name}	boolean	No	Set to true to add the user to this audience, false to remove them.

Examples of audience attributes:

Field	Type	Required	Description
audience_all_users: true	boolean	No	Add user to "all users" audience list.
audience_all_users: false	boolean	No	Remove user from "all users" audience list.
audience_premium_users: true	boolean	No	Add user to "premium users" audience list.
audience_retargeting_list: false	boolean	No	Remove user from retargeting audience list.

Example: Audience-only request

curl -X POST https://s2s.us2.mparticle.com/v2/events \
  --user "your-api-key:your-api-secret" \
  --header "Content-Type: application/json" \
  --header "Charset: utf-8" \
  --data '{
    "environment": "production",
    "user_identities": {
      "email": "customer@example.com"
    },
    "user_attributes": {
      "audience_premium_users": true,
      "audience_retargeting_list": false
    }
  }'

---

Complete Examples

Conversion with Full User Data

{
  "environment": "production",
  "ip": "203.0.113.42",
  "device_info": {
    "http_header_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    "ios_advertising_id": "613ff528-afd1-4c1b-9628-e6ed25ece9c0"
  },
  "user_attributes": {
    "firstname": "John",
    "firstnamesha256": "a8cfcd74832004951b4408cdb0a5dbcd8c7e52d43f1f6c5f9fdb7c3c7a0e2d4",
    "lastname": "Doe",
    "lastnamesha256": "c1572d05424d0ecb2a65ec6a82aeacbf8c7f28f3f8f3a9dfb7a3c8b5d7a6f6a1",
    "mobile": "3125551515",
    "mobilesha256": "f6d7c3a9b82d7cbb6f3d8e4a0c2f5d1b9f6c2a5f4e7d8b3c9a2f5e8d1c4b7a6",
    "age": "33",
    "dob": "19900717",
    "gender": "M",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "title": "Mr",
    "language": "en",
    "value": "52.25",
    "predictedltv": "136.23"
  },
  "user_identities": {
    "email": "john.doe@example.com",
    "customerid": "cust_123456"
  },
  "integration_attributes": {
    "1277": {
      "passbackconversiontrackingid": "e8335d31-2031-4bff-afec-17ffc1784697"
    }
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "source_message_id": "order_789012",
        "timestamp_unixtime_ms": 1735689600000,
        "custom_attributes": {
          "conversiontype": "purchase",
          "confirmationref": "ORD-789012",
          "amount": "149.99",
          "currency": "USD"
        }
      }
    }
  ]
}

Privacy-Focused Request (Hashed Data Only)

{
  "environment": "production",
  "user_identities": {
    "other": "8b1a9953c4611296a827abf8c47804d7e6c49c6b97d"
  },
  "user_attributes": {
    "firstnamesha256": "a8cfcd74832004951b4408cdb0a5dbcd8c7e52d9c3f1f6c5f9fdb7c3c7a0e2d4",
    "lastnamesha256": "c1572d05424d0ecb2a65ec6a82aeacbf8c7f28f3f8f3a9dfb7a3c8b5d7a6f6a1"
  },
  "events": [
    {
      "event_type": "custom_event",
      "data": {
        "event_name": "conversion",
        "custom_event_type": "transaction",
        "source_message_id": "evt_unique_456",
        "timestamp_unixtime_ms": 1735689600000,
        "custom_attributes": {
          "conversiontype": "signup"
        }
      }
    }
  ]
}

---

Error Handling

Status	Code	Description
202	Accepted	The POST was accepted.
400	Bad Request	The request JSON was malformed or had missing fields.
401	Unauthorized	The authentication header is missing.
403	Forbidden	The authentication header is present, but invalid.
429	Too Many Requests	You have exceeded your provisioned limit. The v2/events endpoint may return a Retry-After response header with a value containing a non-negative decimal integer indicating the number of seconds to delay. If the header is not present, we recommend retrying your request with exponential backoff and random jitter.
503	Service Unavailable	We recommend retrying your request in an exponential backoff pattern.
5xx	Server Error	A server-side error has occurred, please try your request again.

In some cases, the server provides additional information in the response body. If no additional information is available, the response body will be omitted and you will only receive the status code and message.

Example response body for an unsuccessful request:

{
    "errors": [
        {
            "code": "BAD_REQUEST",
            "message": "Required event field \"event_type\" is missing or empty."
        }
    ]
}

---

Limits

The following are rate and size limits for the Event API:

Resource	Limit
Total request size	256 KB
Batches per second	270 batches per second
Event name length	256 characters
Event attribute name length	256 characters
Event attribute value length	4096 characters
User attributes per batch	100
User attribute name length	256 characters
User attribute value length	4096 characters

---

Rate Limiting

Rokt enforces rate limits to ensure platform stability. When limits are exceeded, the API returns HTTP 429 Too Many Requests.

Rate Limit Types

Type	Description
Speed	Maximum requests per time window
Acceleration	Maximum rate of traffic increase

Handling Rate Limits

When you receive a 429 response:

1. Check the Retry-After header for the recommended wait time
2. Implement exponential backoff with jitter:

import random

def calculate_backoff(attempt, retry_after=None, max_delay=60):
    base_delay = retry_after if retry_after else 1
    exponential_delay = min(base_delay * (2 ** attempt), max_delay)
    jitter = random.uniform(0, exponential_delay)
    return exponential_delay + jitter

Proactive Rate Management

Successful responses include the X-mp-rate-limit-percentage-used header showing your current usage percentage. Monitor this to adjust your request rate before hitting limits.

X-mp-rate-limit-percentage-used: 75

---

Combining with the Web SDK

For maximum coverage, you can send conversions through both the Web SDK and Event API. Rokt will automatically deduplicate events when you include consistent identifiers.

To enable deduplication, include the same values for conversiontype and confirmationref across both integrations. Rokt uses the combination of these two fields to identify and deduplicate events.

This approach provides:

• Redundancy - Conversions are captured even if one integration fails
• Validation - Compare data from both sources to identify discrepancies

---

Testing

Development Environment

Work with your Rokt account manager to set up testing in a development environment before going to production.

note

The environment field must always be set to "production", even during testing. This field indicates the data format version, not your deployment stage.

Testing Checklist

• Verify authentication works with your credentials
• Send a test event and confirm 202 Accepted response
• Test error handling with invalid payloads
• Verify events appear in Rokt's reporting (coordinate with your account manager)
• Test rate limit handling
• Provide a few test email addresses you have sent to your Rokt account manager to confirm the integration works end to end

---

Support

For questions or assistance with your integration, contact your Rokt account manager who will provide the appropriate resources to help troubleshoot any issues.