POST Events

The Event API allows clients to integrate one or more events with the Rokt platform. Full details are discussed later in this article, however it's worth discussing a few key topics before we go on.

Event type

The Event API can receive and store any event. Sharing events can be useful for conversion attribution, anomaly detection, and advanced reporting use cases. Rokt uses the eventType 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 are 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 always triggers the conversion attribution process. This event type should be used in conjunction with the `conversiontype` `objectData` field so Rokt can differentiate between different types of conversions.

ObjectData payloads

The ObjectData payload is where you should provide relevant information about the event. While you are not required to provide any objectData, we recommend providing any information that improves the effectiveness of Rokt's attribution or anomaly detection systems. Depending on your use case, different sets of attributes are useful.

Payloads for conversion attribution

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.

Other useful data includes:

IP address
First name
Last name
Transaction ID
Coupon ID
Cart ID
Conversion type (Note: Conversion type is particularly useful when the eventType is set to conversion)
Conversion amount
Conversion currency

Payloads for anomoly detection

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, operating system, etc. (Note: Providing the browser user agent string works well)
Platform (e.g., web versus in-app)
Event time
Transaction ID
Country
IP address

Rokt has a data mapping system that 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, we can accept any additional fields if you would like to provide them for reporting purposes.

When to call

Call the Event API to integrate one or more events with the Rokt system.

Request

Sample

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

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 applies the latest version, which could potentially be 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 three hours. A new request will be accepted if the same key is reused after it is expired.

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 Account ID

Event object

The Event object represents 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)	Use metaData to provide non-business critical information; non-exhaustive example use cases; provenance of the data; time of delivery.
objectData	List[objectData Objects]	No	Nullable; up to 100 items (inclusive)	Contains attributes of the event itself, e.g., email address of converting customer, purchase amount, or product name. We can always accept other attributes 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

The ObjectData object 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; 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 ObjectData 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 share additional data fields or use a different name for a particular field, let your account manager know.

Field name	Relevant use case	Description	Example
email	All	Email passed as plain text, lowercase and without trailing spaces	john@email.com
emailsha256	All	SHA256 hash of email address. Prior to hashing, lowercase and without 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 separate multiple items with a comma.	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: If provided, Rokt uses this identifier to deduplicate conversion events across channels.	ABC789
confirmationref	All	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 and `transactionid` is unavailable.	XYZ123
firstname	All	Customer's first name	John
firstnamesha256	All	SHA256 hash of first name. Prior to hashing, lowercase and trim all trailing spaces.	fab1e2e699b3b927cbf875046a64f222 5df02d5cb306f3857424c2bbb87be61f
lastname	All	Customer's last name	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 customer	3053211654, +1 (323) 867-5309
mobilesha256	Conversion attribution, Reporting	SHA256 of mobile number. Note: Mobile number needs to be formatted to a specific format prior to hashing.
ipaddress	All	Customer's IP address	172.3.51.182
ipaddresssha256	All	SHA256 hash of IP address.
useragent	Anomaly detection	Browser user agent of converting customer
DeviceType	Anomaly detection	Type of device	Desktop, Mobile, Tablet
os	Anomaly detection	Device operating system	iOS
osversion	Anomaly detection	Operating system version	8.1
browser	Anomaly detection	Browser	Safari
browserversion	Anomaly detection	Browser version	11.1
title	Reporting		Mr, Mrs, Ms, Miss
gender	Reporting		M, Male, F, Female
dob	Reporting	In the format, yyyyMMdd	19851220
age	Reporting		33
language	Reporting		en, en-US
unitno	Reporting		Unit A
address1	Reporting		123 Sesame St
address2	Reporting		Alphabet Boulevard
zipcode	Reporting		90210, SW1W 0DT
city	Reporting		San Francisco
state	Reporting		CA, California, NY, New York
country	Reporting		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 (See the error tables)
message	string	More detailed description of the error (see the error tables)

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: As a batch API, HTTP Status 200 does not necessarily mean the whole request is processed correctly. Developers should inspect the response payload to ensure all records have been processed successfully. See the BulkResponseItemObject description for more detail.

400 errors

Example:

{
    "data": {
        "code": "",
        "message": ""
    }
}

Error code	Reason
400	Malformed request
401	Unauthorized or invalid authentication token
403	Forbidden; authentication token does not grant operation on specified app_id.
409	Idempotency token has been seen before.

500 errors

Error code	Reason
500, 502, 503	Unexpected error. Retry and/or contact your Rokt support team.

Events

Cart

Confirmation

Placements

Account Level

Campaign Level

Creative Level

Metadata

Subscription

Subscription Event

Calendar

Schedule

Subscribe

Event type

Reserved event types

ObjectData payloads

Payloads for conversion attribution

Payloads for anomoly detection

When to call

Request

Sample

Headers

Body

Event object

MetaData object

ObjectData object

ObjectData fields

Response

Headers

Success body

Error body

BulkResponseObject

BulkResponseItemObject

ErrorObject

200 error

400 errors

500 errors