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

Events

Cart

Confirmation

Placements

Account Level

Campaign Level

Creative Level

Metadata

Event Type

Reserved Event Types

objectData Payloads

When to Call

Sample Request

Request

Headers

Request Body

Event Object

MetaData Object

ObjectData Object

ObjectData Fields

Response

Headers

Success Body

Error Body

BulkResponseObject

BulkresponseItemObject

ErrorObject

200 Error

400 Errors

500 Errors