Last updated

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

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 in absolute terms - ie 10.12 for a $10.12 profit margin.	10.12
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
value	Customer value	19.98
predictedltv	Customer predicted lifetime value	500.0

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": []
    }
}

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 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)

note

This is only for existing users and users onboarding to specific Customer Data Platforms (CDPs) (namely Census, Hightouch, mParticle, Segment, and Tealium). New users of Event API and all other integrations 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

1. Sign in to One Platform.

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

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

4. Enter the name of your app.

5. Click Generate.

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

   AppId: "40svbin0d194subpohl079rhck"
   AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"

7. Store the App ID and App Secret in a secure location. You will not have access to the App Secret again after this session.

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