Last updated May 27, 2025

Event API Integration Guide

In addition to the SDK, Advertisers are recommended to set up a server-to-server integration to send conversion and attribution data from a backend server directly to Rokt via the Event API.

Sending conversion data to Rokt through the Event API provides several benefits:

• Speed: The Event API allows for nearly real-time data forwarding, maximizing the potential of Rokt’s optimization tools.
• Coverage: The Event API allows you to send data from all of your channels and devices, resulting in broader coverage.
• Reliability: Unlike the SDKs, the Event API is not susceptible to interference from web technologies like ad blockers. It also supports error handling, helping you prevent unwanted data loss.

Authentication

Your dedicated Rokt account representative will provide you with your API key and API secret that you can use to authenticate to the Event API.

Depending on your HTTP client, you can authenticate to the API with your key and secret in two ways:

1. Setting your key and secret as your username and password in your client, OR
2. Passing your key and secret in your authentication header.

Username and password

If your HTTP client supports basic authentication, simply set your API key as your username, and your API secret as your password.

Basic authentication header

You can also set the basic authentication header of your HTTP request to the Event API to use your key and secret:

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

   example-api-key:example-api-secret

2. Using Base64/UTF-8, encode your concatenated key and secret. It will resemble:

   ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

3. Prefix this string with the authentication method (Basic) followed by a space.

4. Set this string as the authentication header in your request:

   Authorization: Basic ZXhhbXBsZS1hcGkta2V5OmV4YW1wbGUtYXBpLXNlY3JldA==

Event API Endpoint

The Event API accepts POST requests sent to:

https://s2s.{pod}.mparticle.com/v2/events

Where {pod} is replaced with the data location pod shared with you by your Rokt account representative.

Data localization

Rokt stores and processes your data in isolated, localized regions called pods. Your dedicated Rokt account representative will provide you with the correct pod identifier for your account. Based on the pod identifier they give you, use the corresponding Event API URL according to the table below:

Region	Pod	Event API URL
United States	US1	https://s2s.us1.mparticle.com/v2
United States	US2	https://s2s.us2.mparticle.com/v2
Europe	EU1	https://s2s.eu1.mparticle.com/v2
Australia	AU1	https://s2s.au1.mparticle.com/v2

Create your payload

Rokt requires you to send in the following fields to successfully track a conversion and associate it with a campaign:

Configuration fields

Field name	Datatype	Description
environment	string	Can be either development or production. Indicates if the data is testing data, or live data.

User identities

Field name	Datatype	Description
email	string	The user's email address.
other	string	The user's hashed email address.

note

You must include either the user's raw, unhashed email address using the email field or their hashed email address using the other field. At least one of these identifiers must be included in your payload to the Event API.

User attributes

Field name	Datatype	Description
firstname	string	The user's first name.
lastname	string	The user's last name.
mobile	string	The user's phone number, formatted either as 3053211654, or +1 (323) 867-5309
ipaddress	string	The IP address of the user that converted.

You should include as many user attributes as you can to improve the quality and effectiveness of your attribution data.

Event data

Field name	Datatype	Description
event_type	string	Must be set to custom_event.
event_name	string	The event name must always be set to conversion. You can use the conversion_type field to include additional information about the type of conversion, such as whether it was a purchase or subscription.
amount	decimal	The total price of all items. For example, if the total price of all items is $20, set amount to 20.00.
currency	string	The currency code for the conversion. For example: USD or CAD.
quantity	integer	The number of items within the conversion.
conversiontype	string	The type of conversion that occurred.
productname	string	The name of the item purchased during the conversion.
sku	string	The SKU for the item. If more than one item is present, do not provide any SKUs.
paymenttype	string	The type of payment used. For example: visa.
margin	decimal	The total profit margin of the conversion or transaction, as a percentage. For example, to indicate a margin of $10, set margin to 10.
transactionid	string	The transaction ID of the conversion.
confirmationref	string	Confirmation reference ID. This is an alternative identifier. Note: If provided, Rokt uses this field to deduplicate conversion events.

The body of your request must contain these fields formatted within a JSON object with the following shape:

Example payload:

{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "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"
           }
        }
      }
    ]
}

Send your payload to Rokt

To send your payload to Rokt, send a POST request to https://s2s.{pod}.mparticle.com/v2/events, making sure to replace {pod} with the pod identifier provided by your Rokt account representative.

Example request

curl

curl --location 'https://s2s.mparticle.com/v2/events' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key-secret' \
--data-raw '{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "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,
              "transactionid": "ABC789",
              "confirmationref": "XYZ123"
           }
        }
      }
    ]
}'

HTTP

POST /v2/events HTTP/1.1
Host: s2s.mparticle.com
Content-Type: application/json
Accept: application/json
Authorization: key-secret
Content-Length: 920

{
    "environment": "development",
    "user_identities": {
      "email": "john.doe@example.com",
      "other": "SHA256-hash-of-email"
    },
    "user_attributes": {
      "firstname": "John",
      "lastname": "Doe",
      "mobile": "123-456-7890", 
      "ipaddress": "172.3.51.182"
    },
    "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,
              "transactionid": "ABC789",
              "confirmationref": "XYZ123"
           }
        }
      }
    ]
}

Response

A successful request receives an empty 202 Accepted response.

For an overview of the possible errors that can occur, see Error handling below.

Error handling

Status	Code	Description
400	Bad Request	The request JSON body is malformed or missing required fields.
401	Unauthorized	The auth header is missing.
403	Forbidden	The auth header is present, but invalid.
429	Too Many Requests	The rate limit has been exceeded. The response includes a Retry-After header with a value containing a non-negative decimal integer indicating the number of seconds to wait before retrying. If the Retry-After header is not present, retry your request using exponential backoff and random jitter.
503	Service Unavailable	Retry your request in an exponential backoff pattern.
5xx	Server Error	Internal error, retry your request.

Limits

Following are rate and size limits for the Event API:

Resource	Limit
Total request size	256kb
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