Skip to main content

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

View authentication instructions.

Endpoint#

POST /v1/events

Request#

Header#

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

Parameters#

The request contains events and associated details in JSON format.

Level 1Level 2Level 3RequiredTypeDescription
accountIdYesString; up to 64 charactersRokt Account ID
eventsYesList[EventObject]List of events to be ingested
clientEventIdYesStringAn identifier used to uniquely identify an event within the scope of ${clientId}-${eventType}
eventTypeYesString; up to 128 charactersType of event
eventTimeYesStringTime of the event in RFC 3339
metaDataNoList[metaData]Provides non-business critical information about the event
nameYesStringField name; Prefix rokt. (case-insensitive) is preserved for Rokt use only
valueYesString; up to 65536 charactersField value; for binary value encode with Base64
objectDataNoList[objectData]Contains contextual details of the event
nameYesStringPrefix rokt. (case-insensitive) is preserved for Rokt use only
valueYesString; up to 65536 charactersField 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.

NameDescriptionExample value
emailEmail passed as plain text, lowercase and without trailing spacesjohn@email.com
emailsha256SHA-256 hash of email address. Prior to hashing, lowercase and without trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
passbackconversiontrackingidA Rokt-generated ID used to match conversion events to the originating click. Requires a separate integration.1bc29b36f623ba82aaf6724fd3b16718
amountTransaction amount (allows decimal points)100.25
currencyCurrency codeUSD
quantityThe quantity (integer) of item within the specific conversion4
conversiontypeUsed to differentiate between different conversion events.
Note: Only applicable if the default conversion event type is provided.
ticketpurchase, seatupgrade, signup
productnameThe name of the product(s) purchased. You can separate multiple items with a comma.Maroon 5 t-shirt, Warriors vs. Raptors
skuThe identifier of the product purchased (Note: Only accepts one SKU)230847, tshirt-blue-39487, 398fhdnff
paymenttypeThe payment method used during the transactionVISA, American Express
ccbinCredit card BIN of converting payment123456
marginProfit margin of conversion10
transactionidTransaction ID, used to identify a unique transaction.
Note: If provided, Rokt uses this identifier to deduplicate conversion events across channels.
ABC789
confirmationrefConfirmation 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
firstnameCustomer's first nameJohn
firstnamesha256SHA-256 hash of first name. Prior to hashing, lowercase and trim all trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
lastnameCustomer's last nameSmith
lastnamesha256SHA-256 hash of last name. Prior to hashing, lowercase and trim all trailing spaces.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
mobileMobile phone number of converting customer3053211654, +1 (323) 867-5309
mobilesha256SHA-256 of mobile number.
Note: Mobile number needs to be formatted to a specific format prior to hashing.
fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
ipaddressCustomer's IP address172.3.51.182
ipaddresssha256SHA-256 hash of IP address.fab1e2e699b3b927cbf875046a64f222
5df02d5cb306f3857424c2bbb87be61f
useragentBrowser user agent of converting customerMozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
DeviceTypeType of deviceDesktop, Mobile, Tablet
osDevice operating systemiOS
osversionOperating system version8.1
browserBrowserSafari
browserversionBrowser version11.1
titleTitle of the customerMr, Mrs, Ms, Miss
genderGender of the customerM, Male, F, Female
dobIn the format yyyymmdd19851220
ageAge of the customer33
languageLanguage associated with the purchaseen, en-US
unitnoUnit number associated with addressUnit A
address1First line of street address123 Sesame St
address2Second line of street address (apartment number, floor, etc.)Alphabet Boulevard
zipcodeCustomer postal code90210, SW1W 0DT
cityCustomer citySan Francisco
stateCustomer stateCA, California, NY, New York
countryCustomer countryUS, United States, AU, Australia

Sample#

This is a sample Event API call with a JSON payload containing two booking events.

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

Response#

Header#

NameDescription
X-Rokt-Trace-IdUnique 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.

See errors for more details.

Was this article helpful?