Skip to main content

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

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

  1. Sign in to One Platform.

  2. Navigate to Profile Settings under your account icon at the bottom left.

img

  1. Scroll down to the Generate Personal API Credentials section.

  2. Enter the name of your app.

  3. Click Generate.

  4. Your credentials for both the Event API and Reporting API will generate right away and will look something like this:

    AppId: "40svbin0d194subpohl079rhck"
    AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"
  5. Store the App ID and App Secret in a secure location. You will not have access to the App Secret again after this session.

  6. 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

KeyInDescriptionRequired?Example
Authorizationheaderapp_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)YesBasic base64encocde(12345:abcde)
Content-TypeheaderMedia type of request must always be application/x-www-form-urlencodedYesapplication/x-www-form-urlencoded
grant_typebodyMust be client_credentialsYesclient_credentials

Response

Example

{
"access_token":
"eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA"
"expires_in": 3600,
"token_type": "Bearer"
}

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 /v1/events

Request

Header
NameValueRequiredDescription
Content-Typeapplication/jsonYesN/A
Charsetutf-8YesN/A
AuthorizationBearer ${access-token}YesAccess token retrieved from /auth/oauth2/token endpoint
Rokt-Version2020-05-21YesAPI 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.
Idempotency-Key${uuid-v4}YesUnique identifier from the client used to allow retrying events safely. Subsequent requests with the same idempotency-key would result in HTTP 409. Keys can be purged after three hours. A new request will be accepted if the same key is reused after it is expired.
Parameters

The request contains events and associated details in JSON format.

Level 1Level 2Level 3RequiredTypeDescription
accountIdYesString; up to 64 charactersRokt Account ID
eventsYesList[EventObject]; up to 100 items per callList of events to be ingested
clientEventIdYesString; up to 36 charactersAn identifier used to uniquely identify an event
eventTypeYesString; up to 128 charactersType of event
eventTimeYesStringTime 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.
metaDataNoList[metaData]Provides non-business critical information about the event
nameYesString; up to 256 charactersField name; Prefix rokt. (case-insensitive) is preserved for Rokt use only
valueYesString; up to 65536 charactersField value; for binary value encode with Base64
objectDataNoList[objectData]Contains contextual details of the event
nameYesString; up to 256 charactersPrefix rokt. (case-insensitive) is preserved for Rokt use only
valueYesString; up to 65536 charactersField 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.

NameDescriptionExample value
emailEmail passed as plain text, lowercase and without trailing spacesjohn@email.com
emailsha256SHA-256 hash of email address. Prior to hashing, lowercase and without trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
passbackconversiontrackingidA Rokt-generated ID used to match conversion events to the originating click. Requires a separate integration.1bc29b36f623ba82aaf6724fd3b16718
amountTransaction amount (allows decimal points)100.25
currencyCurrency codeUSD
quantityThe quantity (integer) of item within the specific conversion4
conversiontypeUsed to differentiate between different conversion events.
Note: Only applicable if the default conversion event type is provided.
ticketpurchase, seatupgrade, signup
productnameThe name of the product(s) purchased. You can separate multiple items with a comma.Maroon 5 t-shirt, Warriors vs. Raptors
skuThe identifier of the product purchased (Note: Only accepts one SKU)230847, tshirt-blue-39487, 398fhdnff
paymenttypeThe payment method used during the transactionVISA, American Express
ccbinCredit card BIN of converting payment123456
marginProfit margin of conversion10
transactionidTransaction ID, used to identify a unique transaction.
Note: If provided, Rokt uses this identifier to deduplicate conversion events across channels.
ABC789
confirmationrefConfirmation 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
firstnameCustomer's first nameJohn
firstnamesha256SHA-256 hash of first name. Prior to hashing, lowercase and trim all trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
lastnameCustomer's last nameSmith
lastnamesha256SHA-256 hash of last name. Prior to hashing, lowercase and trim all trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
mobileMobile phone number of converting customer3053211654, +1 (323) 867-5309
mobilesha256SHA-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
ipaddressCustomer's IP address172.3.51.182
ipaddresssha256SHA-256 hash of IP address.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
useragentBrowser user agent of converting customerMozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
DeviceTypeType of deviceDesktop, Mobile, Tablet
osDevice operating systemiOS
osversionOperating system version8.1
browserBrowserSafari
browserversionBrowser version11.1
titleTitle of the customerMr, Mrs, Ms, Miss
genderGender of the customerM, Male, F, Female
dobIn the format yyyymmdd19851220
ageAge of the customer33
languageLanguage associated with the purchaseen, en-US
unitnoUnit number associated with addressUnit A
address1First line of street address123 Sesame St
address2Second line of street address (apartment number, floor, etc.)Alphabet Boulevard
zipcodeCustomer postal code90210, SW1W 0DT
cityCustomer citySan Francisco
stateCustomer stateCA, California, NY, New York
countryCustomer countryUS, United States, AU, Australia
Sample

This is a sample Event API call with a JSON payload containing two booking events.

POST /v1/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

NameDescription
X-Rokt-Trace-IdUnique 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": []
}
}
200 response and potential errors

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 CodeError CodeDescription
200N/ATypically OK, but see example of a 200 error scenario below.
400RequestBodyReadErrorError occurred when reading the request body.
400RequestJsonUnmarshalErrorEvent API was unable to unmarshal the request body.
400RequestValidationErrorThe contents of the request body failed our validation checks. Check that you’ve followed the parameter requirements correctly.
401UnauthorizedErrorUnauthorized or invalid authentication token.
403ForbiddenThe provided access token is not authorized on your account.
500, 502, 503InternalServerError, ServiceUnavailableErrorUnexpected 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 1Level 2Level 3Level 4TypeDescription
dataBulkResponseItemObject
unprocessedRecordsList[BulkResponseItemObject]A list of objects that contain records that failed to process.
errorErrorObjectDescribes the error related to the record.
codeStringError code
messageStringDetailed error message
recordEventObjectField 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"
}
]
}
}
]
}
}
Was this article helpful?