Event API

Deprecation Notice

The Event API documented below is now deprecated and will no longer receive new updates or enhancements. We strongly encourage all clients to migrate to the Event and Audience API Integration Guide, which offers improved reliability, enhanced data structure, and expanded capabilities for conversion tracking and audience management.

Why the change? The Event and Audience API Integration provides a modernized and unified interface for sending conversion and audience data, enabling:

• Enhanced data structure with improved user identity and attribute handling
• Better support for device information and mobile advertising IDs
• Improved error handling and rate limiting capabilities
• Unified interface for both conversion events and audience data
• Scalable support for future data types and integration patterns

Migration Support To assist with your migration, please refer to the Event and Audience API Integration Guide, which includes:

• Complete API reference with request/response examples
• Field mapping from legacy Event API to the new integration
• Authentication and security best practices
• Error handling and rate limiting guidance
• Testing and validation procedures

The Event API offers another option for advertisers looking to integrate conversion data with Rokt. Using the Event API, your backend server can securely connect to Rokt's, transmitting conversion data in real time.

Using the Event API as a standalone integration for conversion data provides multiple benefits:

• Speed: Enables a fully automated, near-real time data exchange, maximizing the potential of Rokt’s automated optimization tools.
• Coverage: Permits integration of events across all channels and devices, resulting in coverage for conversions across web, mobile, and in-store.
• Reliability: As a server-to-server integration, the Event API is not susceptible to any interference by web technologies such as browser or ad blocking. It also supports error handling, ensuring that data is never lost.

Authentication

Reach out to your Rokt account manager to create a public and secret key pair for the accounts for which you would like to submit conversion events. These keys take the form of rpub- and rsec- respectively.

Build your request headers

Name	Value	Required	Description
Content-Type	application/json	Yes	N/A
Charset	utf-8	Yes	N/A
Rokt-Version	2020-05-21	Yes	API version for Rokt. Currently latest version is 2020-05-21. Note: Leaving this header empty applies the latest version, which could potentially be backward incompatible. Invalid value would yield 400 bad request.
Authorization	Basic base64(rpub-...:rsec-...)	Yes	Standard basic authentication header, with the credential value being a base64 encoding of rpub- and rsec- joined by a colon.

Full endpoint reference

View full reference details for the Event API.

Sample

POST /v2/events
{
    "accountId": "12345",
    "events": [
        {
            "clientEventId": "ff3bd69c-ca74-4337-af91-4d5d0bd00e38",
            "eventTime": "2020-05-22T10:21:29.339Z",
          	"eventType": "conversion",
            "objectData": [
                {
                    "name": "email",
                    "value": "email123@emailserver.com"
                },
                {
                    "name": "transactionid",
                    "value": "123456789"
                },
                {
                    "name": "amount",
                    "value": "99.80"
                },
             	  {
                    "name": "currency",
                    "value": "USD"
                },
                {
                    "name": "quantity",
                    "value": "2"
                },
                {
                    "name": "conversiontype",
                    "value": "hotel_booking"
                },
                {
                    "name": "margin",
                    "value": "10"
                },
            ]
        }
    ]

Suggested objectData fields

The objectData object is made up of key-value pairs that contain metadata about the event. In order to properly attribute conversions, you must include one of email (email), SHA-256 hashed email (emailsha256), or Rokt ID (passbackconversiontrackingid) in objectData so that Rokt can identify the customer.

For the conversion reporting use case, we recommend you include the following attributes.

Field name	Description	Example
email	Email passed as plain text, lowercase and without trailing spaces	john@email.com
emailsha256	SHA256 hash of email address. Prior to hashing, lowercase and without trailing spaces.	fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f
passbackconversiontrackingid	Also known as Rokt ID. A Rokt-generated ID used to match conversion events to the originating click. Requires a separate integration.	1bc29b36f623ba82aaf6724fd3b16718
amount	Value of the transaction (allows decimal points)	100.25
currency	Currency code	USD
quantity	The quantity (integer) of item within the specific conversion	4
conversiontype	Used to differentiate between different conversion events. Note: Only applicable if the default conversion event type is provided.	ticketpurchase, seatupgrade signup
productname	The name of the product(s) purchased. You can separate multiple items with a comma.	Maroon 5 t-shirt, Warriors vs. Raptors
sku	The identifier of the product purchased (Note: Only accepts one SKU)	230847, tshirt-blue-39487, 398fhdnff
paymenttype	The payment method used during the transaction	VISA, American Express
margin	Profit margin of conversion in absolute terms - ie 10.12 for a $10.12 profit margin.	10.12
transactionid	Transaction ID, used to identify a unique transaction. Note: If provided, Rokt uses this identifier to deduplicate conversion events across channels.	ABC789
confirmationref	Confirmation reference ID. Alternate identifier that may be used to identify a unique transaction and/or track order confirmations. Note: If provided, Rokt uses this identifier to deduplicate conversion events and transactionid is unavailable.	XYZ123
firstname	Customer's first name	John
lastname	Customer's last name	Smith
mobile	Mobile phone number of converting customer	3053211654, +1 (323) 867-5309
ipaddress	Customer's IP address	172.3.51.182

Custom attributes

Rokt has a data mapping system that allows us to map provided field names to our internal data fields, however we have some recommended field names and formatting requirements later in this article. If you would like to use alternate field names, let us know, and we will ensure your fields are managed accordingly. Additionally, we can accept any additional fields if you would like to provide them for reporting purposes.

Premium integration: Combining the Web SDK and Event API

If possible, we recommend setting up conversion reporting through both the Web SDK and Event API. This helps identify any anomalies and provides redundancy if there are any issues on the frontend or backend.

If you choose to set up both integrations, ensure you populate one of transactionid or confirmationref in both the Web SDK and Event API integrations. Rokt can then deduplicate incoming your conversion events using these variables, ensuring that your reporting is accurate.