POST Events
Allows clients to integrate one or more events with the Rokt platform. Full details will be shared later on in this section, however it's worth discussing a few key topics before we go on.
Event Type
The Event API itself is extremely flexible and will receive and store any event. Some of these events may be used for downstream processes like Conversion Attribution, other events may be used for Anomaly Detection, and others may simply be used for advanced reporting use cases. Rokt will use the Event Type field to know what type of event is provided and ensure that the data is routed correctly.
For example, a client may use the Event API for three different types of events:
- hotel_booking — Used for conversion attribution for a hotel campaign.
- app_download — Used for conversion attribution for an app install campaign.
- confirmation_page_load — Used for anomaly detection on a Rokt Placement on the confirmation page.
You may wish to integrate one or more events with the API. Coordinate with your Rokt Account Manager to ensure that these event names will be appropriately configured in the Rokt Platform.
Reserved Event Types
Certain Event Types have been reserved by Rokt for specific functionality.
Event Type | Description |
---|---|
conversion | A "conversion" event type will always trigger the conversion attribution process. This event type should be used in conjunction with the "conversiontype" objectData field to allow Rokt to differentiate between different types of conversions. |
objectData Payloads
The Object Data payload is where you should provide relevant information about the event. While it is not required to provide any objectData, it is highly recommended to provide information that will improve the effectiveness of Rokt's attribution or anomaly detection systems.
Depending on the use case, we recommend you provide different attributes to Rokt. For Conversion Attribution, we require at least one of the following fields to be provided:
- Email Address
- Phone Number
- Rokt Conversion Tracking ID (if available)
All of the above can be provided raw or SHA256 hashed. Specific hashing instructions will be included in the detailed attribute section of the document.
Other data that may be useful will be:
- IP Address
- First Name
- Last Name
- Transaction ID
- Coupon ID
- Cart ID
- Conversion Type (note: this field is particularly useful if the default "conversion" event type is provided)
- Conversion Amount
- Conversion Currency
When using the API for anomaly detection, we recommend you provide information about the device, platform, and location where the event took place to assist with troubleshooting. Example fields include:
- Device Type, Browser, OS, etc. (note: providing the User Agent string would be perfect here)
- Platform (e.g., web vs in app)
- Event Time
- Transaction ID
- Country
- IP Address
Rokt has a data mapping system which 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 document. If you would like to use alternate field names from the ones provided please let us know and we will ensure your fields are managed accordingly. Additionally, if you would like to provide additional fields for reporting purposes we will be able to accept them.
When to Call
Call the Event API to integrate one or more events with the Rokt system.
Sample Request
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"
}
]
}
]
}
Request
Headers
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 will apply the latest version which could potentially backward incompatible. Invalid value would yield 400 bad request. |
Idempotency-Key | ${uuid-v4} | Yes | Unique 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 3 hours. A new request will be accepted if the same key is reused after it is expired. |
Request Body
The request body contains the actual events.
{
"accountId": "<xxx>",
"events": [
${EventObject}
]
}
Field Name | Type | Required | Constraint | Description |
---|---|---|---|---|
events | List[EventObject] | Yes | Up to 100 items (inclusive) | List of events to be ingested. |
accountId | string | Yes | Up to 64 characters | Rokt AccountId |
Event Object
The event object is the event itself
{
"clientEventId": "",
"eventType": "",
"eventTime": "",
"metaData": [
${MetaDataObject}
],
"objectData": [
${DataumObject}
]
}
Field Name | Type | Required | Constraint | Description |
---|---|---|---|---|
clientEventId | string | Yes | Not nullable; Up to 36 characters; | An identifier used to uniquely identify an event within the scope of ${clientId}-${eventType} |
eventType | string | Yes | Not nullable; Up to 128 characters; | Type of event. E.g., booking, page_impression |
eventTime | rfc3339 datetime string | Yes | Not nullable; Must be a valid RFC3339 string | Time of the event in RFC 3339. E.g., 1911-11-11T11:11:11.11Z |
metaData | List[MetaData] | No | Nullable;Up to 100 items (inclusive) | metaData allows for non business critical information to be provided; non exhaustive example use cases; provenance of the data; time of delivery. |
objectData | List[objectData Objects] | No | Nullable;Up to 100 items (inclusive) | Used to pass attributes of the event itself. E.g., email address of converting user, purchase amount, product name, etc. Some of the other attributes we can receive are documented here. We can always accept other attributes data not listed. |
MetaData Object
{
"name": "",
"value": ""
}
Field Name | Type | Required | Constraint | Description |
---|---|---|---|---|
name | string | yes | Not nullable; Up to 256 characters (inclusive). Note: Prefix "rokt." (case-insensitive) is preserved for Rokt use only; any name starts with it would cause validation error. | Field name |
value | string | yes | Not nullable; up to 65536 characters (inclusive) | Field value; for binary value encode with Base64 |
ObjectData Object
ObjectData is where key attributes are shared about the event. Recommended attributes are included at the end of this section. The structure is quite simple, with a name and a value:
{
"name": "",
"value": ""
}
Field Name | Type | Required | Constraint | Description |
---|---|---|---|---|
name | string | Yes | Not nullable; Up to 256 characters (inclusive). Note: Prefix "rokt." (case-insensitive) is preserved for Rokt use only; any name starts with it would cause validation error. | Field name |
value | string | Yes | Not nullable; Up to 65536 characters (inclusive) | Field value. For binary value encode with Base64 |
ObjectData Fields
Below is a list of standard Object Data fields Rokt accepts in the Event API. As discussed in the introduction, some of these fields are particularly useful for either attribution or anomaly detection, however none are required. If you want to pass additional data fields or use a different name for a particular field let us know.
Parameter | Recommended Use Case | Description | Example |
---|---|---|---|
All | Email passed as plain text/raw lowercased and without trailing spaces | john@email.com | |
emailsha256 | All | SHA256 hash of email address. Prior to hashing lowercase and trim all trailing spaces. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
passbackconversiontrackingid | Conversion Attribution/ Reporting | A Rokt-Generated ID used to match conversion events to the originating click. Requires a separate integration. | 1bc29b36f623ba82aaf6724fd3b16718 |
amount | Conversion Attribution/ Reporting | Transaction amount. Allows decimal points. | 100.25 |
currency | Conversion Attribution/ Reporting | Currency code. | USD |
quantity | Conversion Attribution/ Reporting | The quantity (integer) of item within the specific conversion. | 4 |
conversiontype | Conversion Attribution/ Reporting | Used to differentiate between different conversion events. Note: only applicable if the default "conversion" event type is provided. | ticketpurchase, seatupgrade, signup |
productname | Conversion Attribution/ Reporting | The name of the product(s) purchased. You can comma separate multiple items. | Maroon 5 t-shirt, Warriors vs Raptors |
sku | Conversion Attribution/ Reporting | The persistent identifier(s) of the product purchased. | 230847, tshirt-blue-39487, 398fhdnff |
paymenttype | Conversion Attribution/ Reporting | The payment method used during the transaction | VISA, American Express |
ccbin | Conversion Attribution/ Reporting | credit card BIN of converting payment | 123456 |
margin | Conversion Attribution/ Reporting | Profit margin of conversion | 10 |
transactionid | All | Transaction ID, used to identify a unique transaction. Note: Rokt will use this identifier to deduplicate conversion events across channels if provided. | ABC789 |
confirmationref | All | Confirmation reference ID. Alternate identifier that may be used to identify a unique transaction and/or track order confirmations. Note: Rokt will use this identifier to deduplicate conversion events if provided and transactionid is unavailable. | XYZ123 |
firstname | All | Consumer's first name | John |
firstnamesha256 | All | SHA256 hash of first name. Prior to hashing lowercase and trim all trailing spaces. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
lastname | All | Smith | |
lastnamesha256 | All | SHA256 hash of last name. Prior to hashing lowercase and trim all trailing spaces. | fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f |
mobile | Conversion Attribution/ Reporting | Mobile phone number of converting user. | 3053211654, +1 (323) 867-5309 |
mobilesha256 | Conversion Attribution/ Reporting | SHA256 of Mobile number. Note: mobile will need to be formatted to a specific format prior to hashing | |
ipaddress | All | Consumer's IP address | 172.3.51.182 |
ipaddresssha256 | All | SHA256 hash of IP address | |
useragent | Anomaly Detection | Browser user agent of converting user | |
DeviceType | Anomaly Detection | type of device | Desktop, Mobile, Tablet |
os | Anomaly Detection | Operating system | iOS |
osversion | Anomaly Detection | Operating system Version | 8.1 |
browser | Anomaly Detection | Browser | Safari |
browserversion | Anomaly Detection | Browser Version | 11.1 |
title | Analytics | Mr, Mrs, Ms, Miss | |
gender | Analytics | M, Male, F, Female | |
dob | Analytics | yyyyMMdd E.g., 19851220 | |
age | Analytics | 33 | |
language | Analytics | en, en-US | |
unitno | Analytics | Unit A | |
address1 | Analytics | 123 Sesame St | |
address2 | Analytics | Alphabet Boulevard | |
zipcode | Analytics | 90210, SW1W 0DT | |
city | Analytics | San Francisco | |
state | Analytics | CA, California, NY, New York | |
country | Analytics | US, United States, AU, Australia |
Response
Headers
Name | Description |
---|---|
X-Rokt-Trace-Id | Unique identifier associated with the request, used for troubleshooting purposes. |
Success Body
{
"data": ${BulkResponseObject}
}
Error Body
{
"data": ${ErrorObject}
}
BulkResponseObject
{
"unprocessedRecords": [
${BulkResponseItemObject}
]
}
Field Name | Type | Description |
---|---|---|
unprocessedRecords | List[BulkResponseItemObject] | A list of objects that contain records failed to be processed. |
BulkresponseItemObject
{
"error: ${ErrorObject},
"record": ${EventObject},
}
Field Name | Type | Description |
---|---|---|
record | EventObject | Field Contains the original record that failed. |
error | errorObject | Field describes error related to the record. |
ErrorObject
{
"code": "",
"message": ""
}
Field Name | Type | Description |
---|---|---|
code | string | Name of the error, lookup the error below. |
message | string | More detailed description of the error, lookup the error table below. |
200 Error
Example:
{
"data": {
"unprocessedRecords": [
{
"error": {
"code": "ValidationError",
"message": "wrong stuff, yo"
},
"record": {
"clientEventId": "fff4deeb-cdee-49ff-9aad-61b1c4256ca6",
"eventType": "conversion",
"eventTime": "2020-05-22T10:21:29.339Z",
"metaData": [
{
"name": "foo",
"value": "bar"
}
],
"objectData": [
{
"name": "FOO",
"value": "BBB"
}
]
}
}
]
}
}
Note: Due to the nature of being a batch API, Http Status 200 does not necessarily mean the whole request is processed correctly. Developers still have to inspect the response payload to ensure all records have been processed successfully. See the BulkResponseObject description for more detail.
400 Errors
Example:
{
"data": {
"code": "",
"message": ""
}
}
Error Code | Reason |
---|---|
400 | Malformed request. |
401 | Unauthorized, invalid Auth token. |
403 | Forbidden, Auth token does not grant operation on specified client_id. |
409 | Idempotency token has been seen before. |
500 Errors
Error Code | Reason |
---|---|
500, 502, 503 | Unexpected error. Please retry and/or contact your Rokt support team. |