Last updated Oct 30, 2024

V2 Partner Events API Specification

This document outlines the relevant endpoint necessary to interact with Rokt's API to submit Events to Rokt.

Endpoints

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

Testing Best Practice

The testing endpoint https://server-api-demo.rokt.com/v2/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.

Request

Authorization Headers

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

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

Required Headers

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

Root/Body

Property Name	Required	DataType	Description
Events	Yes	PartnerEvent[]	A collection of events to be sent to Rokt
Integration	Yes	Integration	Data relating to the integration making the request. This can be obtained from the UXHelper libraries available for Android, iOS and web

Integration

Property Name	Required	DataType	Description
Name	Yes	string	Indicates the common name of the integration making the request
Version	Yes	string	Version of the integration making the request
Framework	Yes	string	integration framework being utilized (e.g., Flutter, React Native)
Platform	Yes	string/enum	Partner platform requesting offers (e.g., Web, Mobile, iOS)
LayoutSchemaVersion	Yes	string	Highest compatible schema version for the integration
DeviceLocale	Yes	string	Locale setting from the user’s device
DeviceModel	Yes	string	Device Model for iOS or Build Model for Android
DeviceType	Yes	string	Type of device/form factor (e.g., Phone, Tablet)
OperatingSystem	Yes	string	Operating system of the user’s device
OperatingSystemVersion	Yes	string	OS version of the user’s device
PackageName	Yes	string	Package name or bundle identifier of the host application
PackageVersion	Yes	string	Package version or bundle version of the host application
Metadata	No	Map<string, string>	Additional data related to integration or device

PartnerEvent

Property Name	Required	DataType	Description
EventType	Yes	string	The name of the event being published. Matches an eventType in the Event Types section.
EventTime	Yes	string	The time the event was created as `DateTimeOffset` (ISO String with GMT+0). Example: 2022-04-20T00:11:47.529Z
SessionId	Yes	string	The ID of the session associated with the event. Retrieved from `/experiences` response, see SuccessBody.
ParentGuid	Yes	string	The instance GUID of the linked parent. See Event Types - Parent GUID Source for sourcing this field.
PageInstanceGuid	Yes	string	Unique identifier of the page/view for which offers were retrieved. Retrieved from `/experiences` response, see PageContext.
ClientUniqueId	No	string	An identifier to link Rokt session with the partner session for troubleshooting (e.g., Uber Session ID).
EventData	No	string	Additional data required for the event.
Metadata	No	NameValuePair[]	Collection of additional metadata related to the event.

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

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 type

Event Type	Description
SignalImpression	Raised whenever a layout, slot, or creative is rendered and visible to the customer. If there is an appearance delay involved, this occurs upon unhiding the view. This correlates to the Layout Impressions metric in the One Platform dashboard.
SignalViewed	Raised when a layout is >= 50% visible in the viewport for at least one second.
SignalResponse	Raised when a consumer engages with a response option on a creative.
SignalGatedResponse	Raised when a consumer engages with a "Remind Me Later" response option on a creative.
SignalInitialize	Raised when the library attempts to display layout
SignalDismissal	Triggered when the customer closes or dismiss the layout.
SignalActivation	Triggered when the customer interacts with a layout.
SignalSdkDiagnostic	Triggered when an error occurs within the Rokt layout or during the rendering process. Partners can listen to this event to handle exceptions.

Request Example

JSON Request Body/Payload

Click to expand

{
    "integration": { ... Standard integration payload ... },
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.710Z",
            "parentGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2"
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f"
        },
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionSlot"
                }
            ]
        },
        {
            "eventType": "SignalImpression",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "AdditionalData",
                    "value": "ImpressionCreative"
                }
            ]
        },
        {
            "eventType": "SignalResponse",
            "eventTime": "2022-06-28T07:11:01.711Z",
            "parentGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
            "sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
            "clientUniqueId": "10f7d87b-e879-47b2-9638-a667e63beae2",
            "pageInstanceGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
            "metadata": [
                {
                    "name": "experienceId",
                    "value": "RedButton"
                }
            ]
        }
    ]
}

Response

Success Response (200)

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

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

Example

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

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.

Click to expand

{
    "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)

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 Error

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

Empty Events Request

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

Empty Body Request

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

Error

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

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.

Endpoints​

Testing Best Practice​

Request​

Authorization Headers​

Required Headers​

Root/Body​

Integration​

PartnerEvent​

NameValuePair​

Event type​

Request Example​

Response​

Success Response (200)​

Root/Body​

UnprocessedEvent​

Example​

Partial Success Response (207)​

Request Error Response (4XX)​

Root/Body​

Validation Error​

Empty Events Request​

Empty Body Request​

Error​

Internal Server Errors (HTTP 5xx)​

Endpoints

Testing Best Practice

Request

Authorization Headers

Required Headers

Root/Body

Integration

PartnerEvent

NameValuePair

Event type

Request Example

Response

Success Response (200)

Root/Body

UnprocessedEvent

Example

Partial Success Response (207)

Request Error Response (4XX)

Root/Body

Validation Error

Empty Events Request

Empty Body Request

Error

Internal Server Errors (HTTP 5xx)