Server Events API Specification

This document outlines the relevant endpoints necessary to interact with Rokt's APIs to submit Events to Rokt.

Please work with your Account Manager to obtain the necessary credentials to interact with this endpoint

EndpointsDirect link to Endpoints

Environment	Action	URL
Production	`POST`	`https://server-api.rokt.com/v1/partner/events`
Testing	`POST`	`https://server-api-demo.rokt.com/v1/partner/events`

Testing Best PracticeDirect link to Testing Best Practice

The testing endpoint https://server-api-demo.rokt.com/v1/partner/events is specifically designed for testing and should be used to validate the integration without affecting production data or performance. Ensure the appropriate headers and request formats are used as specified in the API documentation to emulate production-like scenarios effectively.

RequestDirect link to Request

Authorization HeadersDirect link to Authorization Headers

Header-key	Description	Type	Note
rokt-pub-id	Contains the provided client public id	string	This will be provided by Rokt.
rokt-secret	Contains the provided client public secret which must match the public id	string	This will be provided by Rokt.

Required HeadersDirect link to Required Headers

Header-key	Description	Type	Example
content-type	Media type	string	“application/json”
accept	Expected media type of response	string	“application/json”
rokt-tag-id	Rokt Tag ID	string	1234567890

Root/BodyDirect link to Root/Body

Property Name	Required	DataType	Description
events	Yes	PartnerEvent[]	A collection of events to be sent to Rokt

PartnerEventDirect link to PartnerEvent

Property Name	Required	DataType	Description
eventType	Yes	string	The name of the event being published. Matches an EventType in the Event Type section.
eventTime	Yes	string	The time which the event was created as DateTimeOffset (ISO String with GMT+0 ) e.g: 2022-04-20T00:11:47.529Z
sessionId	Yes	string	The ID of the session which the event is associated with. Retrieved from /offers response, see Key Fields
parentGuid	Yes	string	The instance GUID of the linked parent. See Event Types - Parent GUID Source for where to source this field.
clientUniqueId	Yes	string	An identifier to link Rokt session with the partner session for troubleshooting: <Transaction ID>
metadata	Optional	NameValuePair[]	Collection of additional metadata related to the event

NameValuePairDirect link to NameValuePair

Property Name	Required	DataType	Description
Name	Yes	string	Name/Identifier of the property being provided
Value	Yes	string	Data related to the provided Name

note

Event instanceGuid creation will now be handled by Rokt APIs
Common metadata will be added by Rokt APIs
Endpoint only allows a maximum of 25 events to be processed at a time
All events belonging to the same request must share the same session identifier: sessionId
EventTime per event must be:
- Not future dated (5m leeway)
- Not more than three (3) days in the past

Event typeDirect link to Event type

Event type	Description
SignalImpression	Raised whenever a placement, slot, or creative is rendered and visible to the customer. If there is an appearance delay involved then this occurs upon unhiding the view. This correlates to the Placement Impressions metric in the One Platform dashboard. Required for each placementGuid/slotGuid/creativeGuid.
SignalViewed	Raised when a placement is >= 50% visible in the viewport for at least one continuous second. This matches the Viewability definition set by the Interactive Advertising Bureau (IAB) and should also exclude non-human (bot) traffic, fraudulent impressions, or any form of invalid activity. Required for each creativeGuid.
SignalResponse	Raised when a consumer engages with a response option on a creative. Required for each responseOptionGuid.

note

The slotGuid, creativeGuid, placementGuid, and responseOptionGuid to use in the parentGuid field can be found in the Offers API response.

Request ExampleDirect link to Request Example

JSON Request Body/Payload

{
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394", // This should be a slotGuid, creativeGuid, or placementGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionSlot"
                }
            ]
        },
        {
            "eventType": "SignalViewed",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd", // This should be a creativeGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionCreative"
                }
            ]
        },
        {
            "eventType": "SignalResponse",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863", // This should be a responseOptionGuid
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "metadata": [
                {
                    "name": "experienceId",
                    "value": "RedButton"
                }
            ]
        }
    ]
}'

ResponseDirect link to Response

Success Response (200)Direct link to Success Response (200)

Root/BodyDirect link to Root/Body

Property Name	DataType	Description
success	boolean	Indicates whether the events were successfully received by Rokt
processedEventsCount	number/int	Indicates the number of events which were successfully accepted by Rokt
unprocessedEvents	UnprocessedEvent[]	Collection of events that were not accepted along with errors descriptions per event

UnprocessedEventDirect link to UnprocessedEvent

Property Name	DataType	Description
event	PartnerEvent	Indicates whether the events were successfully received by Rokt
errors	Error[]	Indicates the number of events which were successfully accepted by Rokt

ExampleDirect link to Example

{ 
    "processedEventsCount": 5, 
    "unprocessedEvents": [], 
    "success": true }

Partial Success Response (207)Direct link to Partial Success Response (207)

In the case where valid events are sent with invalid events, Rokt will still attempt to process the valid events and return a mixed response (HTTP 207) status, indicating the number that were accepted and providing the events which were not.

{
    "processedEventsCount": 5,
    "unprocessedEvents": [
        {
            "errors": [
                {
                    "code": "InvalidEventType",
                    "message": "Event type is invalid"
                },
                {
                    "code": "SessionIdMissing",
                    "message": "SessionId is missing or invalid"
                },
                {
                    "code": "ParentGuidIsMissing",
                    "message": "ParentGuid is null or empty"
                },
                {
                    "code": "EventTimeIsMissing",
                    "message": "EventTime is null or default"
                }
            ],
            "event": {
                "eventType": "Unknown",
                "sessionId": "",
                "eventTime": "0001-01-01T00:00:00+00:00",
                "parentGuid": "",
                "clientUniqueId": "265d3a90-4c84-4c17-99af-e09b862b925c"
            }
        }
    ],
    "success": false
}

Request Error Response (4XX)Direct link to Request Error Response (4XX)

Root/BodyDirect link to Root/Body

Property Name	DataType	Description
title	string	Top level failure reason
status	number	HTTP Status code
success	boolean	Indicates whether the request was successful
errors	Error[]	Collection of validation errors which occurred

Validation ErrorDirect link to Validation Error

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "TooManyEvents",
            "message": "The number of events provided exceeds the limit 25"
        }
    ]
}

Empty Events RequestDirect link to Empty Events Request

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "NoEventsProvided",
            "message": "Events cannot be null or empty"
        }
    ]
}

Empty Body RequestDirect link to Empty Body Request

{
    "title": "BadRequest",
    "status": 400,
    "success": false,
    "errors": [
        {
            "code": "InvalidRequestPayload",
            "message": "Request body format is not valid"
        }
    ]
}

ErrorDirect link to Error

Property Name	DataType	Description
code	string	Corresponding error code
message	string	Message describing the error

Internal Server Errors (HTTP 5xx)Direct link to Internal Server Errors (HTTP 5xx)

In rare circumstances a system may unexpectedly be unable to complete a request. In this case, we will return a request without a body with an appropriate status code that complies with standard HTTP response codes. In the case where this response occurs, we recommend that the request be retried after a brief delay (1-2 seconds). If the problem persists or consistently occurs, please reach out to support(support@rokt.com) to assist in identifying and correcting the issue.