Rokt Documentation
  • Documentation
  • User Guide
  • SDK
  • API
  • Third-Party Integrations
  • Help

›Events

Getting Started

  • Introduction

Transactions

    Events

    • Overview
    • Authentication
    • POST Events

    Cart

    • Overview
    • POST Reserve Cart Items
    • POST Confirm Cart Items
    • POST Release Cart Items

    Confirmation

    • POST Cancel Confirmed Item

    Placements

    • POST Any Placements

Customer Data

  • Referral Export
  • Transaction Export
  • Custom Audience Import
  • Unsubscribe Import
  • Attributes

Reporting

  • Overview
  • Authentication
  • Account Level

    • GET Account Summary
    • GET Account Campaigns Overview
    • GET Account Campaigns Breakdown
    • GET Account Campaigns Histogram
    • GET Account Transactions Overview
    • GET Account Transactions Breakdown

    Campaign Level

    • GET Campaign Overview
    • GET Campaign Breakdown
    • GET Campaign Histogram

    Creative Level

    • GET Creative Overview
    • GET Creative Breakdown

    Metadata

    • GET Campaign Metadata
    • GET Audience Metadata
    • GET Creative Metadata
    • GET Accounts Metadata

Rokt Calendar

  • Overview
Edit

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:

  1. hotel_booking — Used for conversion attribution for a hotel campaign.
  2. app_download — Used for conversion attribution for an app install campaign.
  3. 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 TypeDescription
conversionA "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

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 will apply the latest version which could potentially 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 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 NameTypeRequiredConstraintDescription
eventsList[EventObject]YesUp to 100 items (inclusive)List of events to be ingested.
accountIdstringYesUp to 64 charactersRokt AccountId

Event Object

The event object is the event itself

{
    "clientEventId": "",
    "eventType": "",
    "eventTime": "",
    "metaData": [       
        ${MetaDataObject}
    ],
    "objectData": [       
        ${DataumObject}
    ]
}
Field NameTypeRequiredConstraintDescription
clientEventIdstringYesNot nullable; Up to 36 characters;An identifier used to uniquely identify an event within the scope of ${clientId}-${eventType}
eventTypestringYesNot nullable; Up to 128 characters;Type of event. E.g., booking, page_impression
eventTimerfc3339 datetime stringYesNot nullable; Must be a valid RFC3339 stringTime of the event in RFC 3339. E.g., 1911-11-11T11:11:11.11Z
metaDataList[MetaData]NoNullable;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.
objectDataList[objectData Objects]NoNullable;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 NameTypeRequiredConstraintDescription
namestringyesNot 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
valuestringyesNot 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 NameTypeRequiredConstraintDescription
namestringYesNot 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
valuestringYesNot 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.

ParameterRecommended Use CaseDescriptionExample
emailAllEmail passed as plain text/raw lowercased and without trailing spacesjohn@email.com
emailsha256AllSHA256 hash of email address. Prior to hashing lowercase and trim all trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
passbackconversiontrackingidConversion Attribution/ ReportingA Rokt-Generated ID used to match conversion events to the originating click. Requires a separate integration.1bc29b36f623ba82aaf6724fd3b16718
amountConversion Attribution/ ReportingTransaction amount. Allows decimal points.100.25
currencyConversion Attribution/ ReportingCurrency code.USD
quantityConversion Attribution/ ReportingThe quantity (integer) of item within the specific conversion.4
conversiontypeConversion Attribution/ ReportingUsed to differentiate between different conversion events.
Note: only applicable if the default "conversion" event type is provided.
ticketpurchase, seatupgrade, signup
productnameConversion Attribution/ ReportingThe name of the product(s) purchased. You can comma separate multiple items.Maroon 5 t-shirt, Warriors vs Raptors
skuConversion Attribution/ ReportingThe persistent identifier(s) of the product purchased.230847, tshirt-blue-39487, 398fhdnff
paymenttypeConversion Attribution/ ReportingThe payment method used during the transactionVISA, American Express
ccbinConversion Attribution/ Reportingcredit card BIN of converting payment123456
marginConversion Attribution/ ReportingProfit margin of conversion10
transactionidAllTransaction ID, used to identify a unique transaction.
Note: Rokt will use this identifier to deduplicate conversion events across channels if provided.
ABC789
confirmationrefAllConfirmation 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
firstnameAllConsumer's first nameJohn
firstnamesha256AllSHA256 hash of first name. Prior to hashing lowercase and trim all trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
lastnameAllSmith
lastnamesha256AllSHA256 hash of last name. Prior to hashing lowercase and trim all trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
mobileConversion Attribution/ ReportingMobile phone number of converting user.3053211654, +1 (323) 867-5309
mobilesha256Conversion Attribution/ ReportingSHA256 of Mobile number.
Note: mobile will need to be formatted to a specific format prior to hashing

ipaddressAllConsumer's IP address172.3.51.182
ipaddresssha256AllSHA256 hash of IP address
useragentAnomaly DetectionBrowser user agent of converting user
DeviceTypeAnomaly Detectiontype of deviceDesktop, Mobile, Tablet
osAnomaly DetectionOperating systemiOS
osversionAnomaly DetectionOperating system Version8.1
browserAnomaly DetectionBrowserSafari
browserversionAnomaly DetectionBrowser Version11.1
titleAnalyticsMr, Mrs, Ms, Miss
genderAnalyticsM, Male, F, Female
dobAnalyticsyyyyMMdd E.g., 19851220
ageAnalytics33
languageAnalyticsen, en-US
unitnoAnalyticsUnit A
address1Analytics123 Sesame St
address2AnalyticsAlphabet Boulevard
zipcodeAnalytics90210, SW1W 0DT
cityAnalyticsSan Francisco
stateAnalyticsCA, California, NY, New York
countryAnalyticsUS, United States, AU, Australia

Response

Headers

NameDescription
X-Rokt-Trace-IdUnique identifier associated with the request, used for troubleshooting purposes.

Success Body

{
    "data": ${BulkResponseObject}
}

Error Body

{
    "data": ${ErrorObject}
}

BulkResponseObject

{
    "unprocessedRecords": [
        ${BulkResponseItemObject}
    ]
}
Field NameTypeDescription
unprocessedRecordsList[BulkResponseItemObject]A list of objects that contain records failed to be processed.

BulkresponseItemObject

{
    "error: ${ErrorObject},
    "record": ${EventObject},
}
Field NameTypeDescription
recordEventObjectField Contains the original record that failed.
errorerrorObjectField describes error related to the record.

ErrorObject

{
    "code": "",
    "message": ""
}
Field NameTypeDescription
codestringName of the error, lookup the error below.
messagestringMore 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 CodeReason
400Malformed request.
401Unauthorized, invalid Auth token.
403Forbidden, Auth token does not grant operation on specified client_id.
409Idempotency token has been seen before.

500 Errors

Error CodeReason
500, 502, 503Unexpected error. Please retry and/or contact your Rokt support team.
← AuthenticationOverview →
  • 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
RESOURCES
DocumentationUser GuideSDKAPIIntegration PartnersHelp
COMPANY
About UsContact UsCareersEngineering Blog
Rokt Documentation
Copyright © Rokt 2021 - All Rights Reserved