Event API
Overview
Rokt’s Event API is a flexible and robust interface that can support any type of client event (e.g., purchase, app open, or store visit) along with any associated attributes (e.g., email address, purchase amount, credit card BIN).
Rokt Ecommerce partners can use the Event API in conjunction with the Web SDK for anomaly detection, helping catch inconsistencies in placement behavior.
Rokt Ads clients can use the Event API to integrate conversion data with Rokt, improving campaign performance and optimization.
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-*****-* |
API Endpoint
POST Events
The Event API allows clients to integrate one or more events with the Rokt platform. Events typically refer to conversion or transaction events, but usage is flexible.
The Event API has two main use cases: anomaly detection (for partners) and conversion reporting (for advertisers).
POST /v2/events
Request
Header
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. |
Parameters
The request contains events and associated details in JSON format.
Level 1 | Level 2 | Level 3 | Required | Type | Description |
---|---|---|---|---|---|
accountId | Yes | String; up to 64 characters | Rokt Account ID | ||
events | Yes | List[EventObject]; up to 100 items per call | List of events to be ingested | ||
clientEventId | Yes | String; up to 36 characters | An identifier used to uniquely identify an event | ||
eventType | Yes | String; up to 128 characters | Type of event | ||
eventTime | Yes | String | Time of the event must be in UTC and RFC 3339. The request will be rejected if it contains an event with a timestamp that is older than 18 months or more than 5 minutes into the future from the time that the Event API receives it. Events with timestamps that are outside of this range are not processed. | ||
metaData | No | List[metaData] | Provides non-business critical information about the event | ||
name | Yes | String; up to 256 characters | Field name; Prefix rokt. (case-insensitive) is preserved for Rokt use only | ||
value | Yes | String; up to 65536 characters | Field value; for binary value encode with Base64 | ||
objectData | No | List[objectData] | Contains contextual details of the event | ||
name | Yes | String; up to 256 characters | Prefix rokt. (case-insensitive) is preserved for Rokt use only | ||
value | Yes | String; up to 65536 characters | Field value; for binary value encode with Base64 |
Standard objectData
fields
Below is a list of standard objectData
fields that Rokt accepts through the Event API. Based on your use case, some fields are more relevant than others. See anomaly detection or conversion reporting for specific payload samples based on your use case.
If you want to add additional data fields or use a different name for a particular field, let your account manager know.
Name | Description | Example value |
---|---|---|
email | Email passed as plain text, lowercase and without trailing spaces | john@email.com |
emailsha256 | SHA-256 hash of email address. Prior to hashing, lowercase and without trailing spaces. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
passbackconversiontrackingid | A Rokt-generated ID used to match conversion events to the originating click. Requires a separate integration. | 1bc29b36f623ba82aaf6724fd3b16718 |
amount | Transaction amount (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 |
ccbin | Credit card BIN of converting payment | 123456 |
margin | Profit margin of conversion | 10 |
transactionid | Transaction ID, used to identify a unique transaction. | 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. | XYZ123 |
firstname | Customer's first name | John |
firstnamesha256 | SHA-256 hash of first name. Prior to hashing, lowercase and trim all trailing spaces. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
lastname | Customer's last name | Smith |
lastnamesha256 | SHA-256 hash of last name. Prior to hashing, lowercase and trim all trailing spaces. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
mobile | Mobile phone number of converting customer | 3053211654 , +1 (323) 867-5309 |
mobilesha256 | SHA-256 of mobile number. Note: Mobile number needs to be formatted to this specific format prior to hashing: 5551234567 (not containing dashes or spaces). | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
ipaddress | Customer's IP address | 172.3.51.182 |
ipaddresssha256 | SHA-256 hash of IP address. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
useragent | Browser user agent of converting customer | Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 |
DeviceType | Type of device | Desktop , Mobile , Tablet |
os | Device operating system | iOS |
osversion | Operating system version | 8.1 |
browser | Browser | Safari |
browserversion | Browser version | 11.1 |
title | Title of the customer | Mr , Mrs , Ms , Miss |
gender | Gender of the customer | M , Male , F , Female |
dob | In the format yyyymmdd | 19851220 |
age | Age of the customer | 33 |
language | Language associated with the purchase | en , en-US |
unitno | Unit number associated with address | Unit A |
address1 | First line of street address | 123 Sesame St |
address2 | Second line of street address (apartment number, floor, etc.) | Alphabet Boulevard |
zipcode | Customer postal code | 90210 , SW1W 0DT |
city | Customer city | San Francisco |
state | Customer state | CA , California , NY , New York |
country | Customer country | US , United States , AU , Australia |
Sample
This is a sample Event API call with a JSON payload containing two booking events.
POST /v2/events
{
"accountId": "12345",
"events": [
{
"clientEventId": "ff3bd69c-ca74-4337-af91-4d5d0bd00e38",
"eventType": "booking",
"eventTime": "2020-05-22T10:21:29.339Z",
"metaData": [
{
"name": "sourceServer",
"value": "192.0.0.1"
}
],
"objectData": [
{
"name": "email",
"value": "email123@emailserver.com"
},
{
"name": "amount",
"value": "85.00"
}
]
},
{
"clientEventId": "fff4deeb-cdee-49ff-9aad-61b1c4256ca6",
"eventType": "booking",
"eventTime": "2020-05-22T10:21:29.339Z",
"metaData": [
{
"name": "sourceServer",
"value": "192.0.0.1"
}
],
"objectData": [
{
"name": "email",
"value": "email456@emailserver.com"
},
{
"name": "amount",
"value": "99.99"
}
]
}
]
}
Response
Header
Name | Description |
---|---|
X-Rokt-Trace-Id | Unique identifier associated with the request, used for troubleshooting purposes. |
Body
Successful calls to the Event API return a 200 status. The unprocessedRecords
object should be empty, indicating that all events were processed successfully.
Sample
The code sample below represents a successful call to the Event API.
{
"data": {
"unprocessedRecords": []
}
}
When you validate a 200 response, make sure there are no events returned in unprocessedRecords
. If there are records in unprocessedRecords
, one or more of your events may not have processed correctly.
Responses
HTTP Response Code | Error Code | Description |
---|---|---|
200 | N/A | Typically OK, but see example of a 200 error scenario below. |
400 | RequestBodyReadError | Error occurred when reading the request body. |
400 | RequestJsonUnmarshalError | Event API was unable to unmarshal the request body. |
400 | RequestValidationError | The contents of the request body failed our validation checks. Check that you’ve followed the parameter requirements correctly. |
401 | UnauthorizedError | Unauthorized or invalid authentication token. |
403 | Forbidden | The provided access token is not authorized on your account. |
500, 502, 503 | InternalServerError, ServiceUnavailableError | Unexpected errors on Rokt's end. Retry using exponential backoff or contact your Rokt support team. |
Sample
{
"data": {
"code": "RequestJsonUnmarshalError",
"message": "unable to unmarshal request body"
}
}
200 error scenario
HTTP Status 200
typically indicates a successful call. However, as the Event API is a batch API, a 200
response does not necessarily mean the whole request processed correctly. Developers should inspect the response payload to ensure all records have been processed. The response payload contains an error message as well as the specific event object that failed.
Level 1 | Level 2 | Level 3 | Level 4 | Type | Description |
---|---|---|---|---|---|
data | BulkResponseItemObject | ||||
unprocessedRecords | List[BulkResponseItemObject] | A list of objects that contain records that failed to process. | |||
error | ErrorObject | Describes the error related to the record. | |||
code | String | Error code | |||
message | String | Detailed error message | |||
record | EventObject | Field contains the original record that failed. |
{
"data": {
"unprocessedRecords": [
{
"error": {
"code": "ValidationError",
"message": "Invalid content"
},
"record": {
"clientEventId": "fff4deeb-cdee-49ff-9aad-61b1c4256ca6",
"eventType": "conversion",
"eventTime": "2020-05-22T10:21:29.339Z",
"objectData": [
{
"name": "firstname",
"value": "john"
}
]
}
}
]
}
}
Legacy Authentication (v1)
Existing users and users onboarding to specific Customer Data Platforms (CDPs) (namely Census, Hightouch, mParticle, Segment, and Tealium) New users of Event API should use the /v2/events for a simpler authentication experience.
The Event API leverages the OAuth 2.0 approach to client integration. See OAuth 2.0 Credentials Flow for more details. You need your Rokt App ID and App Secret to access the Rokt Event API.
You can generate credentials for the Rokt Reporting API with these same steps.
An access token is needed to call any endpoint on the Rokt Event API. Access tokens allow Rokt to identify client apps, the type of data that each client app is accessing, and prevent malicious apps from accessing data that they do not have access to.
Generating App ID and App Secret
Sign in to One Platform.
Navigate to Profile Settings under your account icon at the bottom left.
Scroll down to the Generate Personal API Credentials section.
Enter the name of your app.
Click Generate.
Your credentials for both the Event API and Reporting API will generate right away and will look something like this:
AppId: "40svbin0d194subpohl079rhck"
AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"Store the App ID and App Secret in a secure location. You will not have access to the App Secret again after this session.
You can use these credentials right away.
You should keep the credentials confidential in order to protect your account and they should never be emailed. Do not share them outside your organization, even if an inquiry appears to come from Rokt. No one who legitimately represents Rokt will ever ask you for your App Secret.
When to call
Call this endpoint to generate an access token that allows you to interact with the Event API for one hour. If you need to continue interacting with the API for over an hour, call this endpoint again to get a new access token.
Request
Sample
curl -vX POST https://api.rokt.com/auth/oauth2/token \
-H 'Authorization: Basic ${AuthToken}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'
Fields
Key | In | Description | Required? | Example |
---|---|---|---|---|
Authorization | header | app_id and app_secret must be passed in the authorization header through Basic HTTP authorization and can be generated under Profile Settings in One Platform; the header content is Basic base64encode(app_id:app_secret) | Yes | Basic base64encocde(12345:abcde) |
Content-Type | header | Media type of request must always be application/x-www-form-urlencoded | Yes | application/x-www-form-urlencoded |
grant_type | body | Must be client_credentials | Yes | client_credentials |
Response
Example
{
"access_token":
"eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA"
"expires_in": 3600,
"token_type": "Bearer"
}
POST /v1/events
Request
The request is identical in all aspects to POST /v2/events
save for the header, which takes the following form:
Header
Name | Value | Required | Description |
---|---|---|---|
Content-Type | application/json | Yes | N/A |
Charset | utf-8 | Yes | N/A |
Authorization | Bearer ${access-token} | Yes | Access token retrieved from /auth/oauth2/token endpoint |
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 . |