V2 Partner Experiences API

This document outlines the relevant endpoints necessary to interact with Rokt's APIs to retrieve Experiences content from Rokt. The endpoint is designed to serve offer-powered experiences directly to partners. Requests are sent to this endpoint, and the response is passed to the UX Helper library for proper handling.

Endpoints

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

Testing Best Practice

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

Body

Property Name	Required	DataType	Description
sessionId	No	string	Session ID of the existing Rokt Session, if exists
pageIdentifier	Yes	string	Text used to differentiate views
attributes	Yes	Map<string, string>	Holds user attribute data to be used during offer selection
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

Request Example

JSON Request Body/Payload

Click to expand

{
    "attributes": {
        "email": "test@rokt.com",
        "locale": "en-AU"
    },
    "pageIdentifier": "your_page_identifier",
    "integration": {
        "name": "UX Helper iOS",
        "version": "1.0",
        "framework": "Swift",
        "platform": "iOS",
        "layoutSchemaVersion": "2.1.0",
        "packageVersion": "1.0.0",
        "packageName": "com.partner",
        "operatingSystem": "iOS",
        "operatingSystemVersion": "18",
        "deviceType": "Phone",
        "deviceModel": "iPhone",
        "metadata": {
          "IsCharging": "true"
        }
    },
}

Response

Success Response (200)

Headers

These headers will be returned for consistency with other Ecommerce APIs, but there is no expectation that they will be consumed by the partner or the UX library.

Header-key	Description
rokt-account-id	Account ID for which offers were served
rokt-session-id	Associated Rokt Session ID
etag	Rokt etag value for the user

Success Body

Root

Property Name	Type	Description
PageContext	PageContext	Data relating to the detected page
Plugins	Layout[]	Plugin object and fonts
SessionId	string	Rokt Session ID. For Web, this Session ID is consumed from the header
Success	bool	Indicates whether the request was successful or invalid
Token	string	Session level Data Integrity JWT
Options	SdkOptions	Collection of runtime configuration to be provided to consuming Rokt SDKs

SdkOptions

Property Name	Type	Description
UseDiagnosticEvents	bool	Indicates whether Rokt SDK should output diagnostics

PageContext

Property Name	Type	Description
IsPageDetected	bool	Indicates if the request resulted in matching a Partner page
PageId	string	GUID representing the matched OP Page configuration
PageInstanceGuid	string	GUID representing a specific instance of the selected page
PageVariantName	string	Name of the selected Page Variant
PartnerContentTemplate	string	Template used for Payments experiences
RoktTagId	string	Partner/Advertiser Tag ID
Token	string	Page level Data Integrity JWT

LayoutPlugin

Property Name	Type	Description
Fonts	Font[]	Array of Fonts to be leveraged by SDKs for the offer
Plugin	Plugin	Plugin configuration

Plugin

Property Name	Type	Description
Config	PluginConfig	Defines config for rendering the layout
Id	string	Layout ID / Transaction Layout External ID
Name	string	Name of the plugin to be used for rendering
TargetElementPosition	string	Action for position placement based on targetElementSelector
TargetElementRelation	string	Relationship between placement and targetElementSelector
TargetElementSelector	string	Identified position to place layout within the page
TargetSection	string	Identifies different targeting types, e.g., Thank You page
Url	string	URL to download the plugin

PluginConfig

Property Name	Type	Description
InstanceGuid	string	GUID representing a specific instance of the plugin / layout
LayoutSchemaVersion	string	Version of the layout schema used for the layout
OuterLayoutSchema	string	JSON schema defining the UI of the Outer Layout
Slots	Slot []	Collection of offer slots
Token	string	Plugin / Layout level Data Integrity JWT

Slot

Property Name	Type	Description
InstanceGuid	string	GUID representing a specific instance of the Slot
LayoutVariant	LayoutVariant	Definition of the LayoutVariant to be used for the Slot / Offer
Offer	Offer	Definition of the Offer to be used for display for our customers
Token	string	Plugin / Layout level Data Integrity JWT

LayoutVariant

Property Name	Type	Description
LayoutVariantId	string	Autogenerated ID
ModuleName	string	The Layout Module name
FormatType	string	Format type to display an offer
LayoutVariantSchema	string	JSON schema defining the UI to render the offers which leverage the variant

Offer

Property Name	Type	Description
AccountId	long	The Rokt account ID associated with the offer
CampaignId	string	ID of the linked campaign in OP
Creative	Creative	Offer creative defined in OP
Metadata	string	Contains metadata related to the offer

Creative

Property Name	Type	Description
ReferralCreativeId	string	ID associated with the creative configuration
InstanceGuid	string	GUID representing a specific instance of the Creative
Copy	Map<string, string>	Contains text related to the offer content
ResponseOptionsMap	Map<string, ResponseOption>	Configuration for CTA buttons
Links	Map<string, Link>	Links available for the offer, references by Layout Schema
Images	Map<string, Image>	Images available for the offer, references by Layout Schema
Icons	Map<string, Icon>	Icons available for the offer, references by Layout Schema
Token	string	Creative level Data Integrity JWT

Font

Property Name	Data Type	Description
FontFamily	string	Specifies the font family (e.g., Arial, Helvetica).
FontStyle	string	Specifies the font style (e.g., normal, italic).
FontWeight	string	Specifies the font weight (e.g., normal, bold).
Src	string[]	An array of source URLs or paths for the font files.

Response Option

Property Name	DataType	Description
action	string	The action of the response
responseOptionGuid	string	A GUID generated which is unique to the response option and to be sent as a part of events calls
signalType	string	The EventType to use when sending event upon interaction. This will almost always be SignalResponse
label	string	Label to be displayed on button/link
successText	string	Text to be displayed upon interaction (not relevant for the pilot)
isPositive	boolean	Indicates whether the response is a positive or negative engagement
url	string	URL on which to perform the action

Request Error Response (HTTP 4xx)

Root/Body

Property Name	Type	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

Error

Property Name	Type	Description
code	string	Corresponding error code
message	string	Message describing the error
value	boolean	Provided value that was invalid, if any

Success Response Body

Success Response

Click to expand

{
    "sessionId": "b1fb003c-e904-4083-b7b9-03cde555a7a1",
    "pageContext": {
        "pageInstanceGuid": "b1fb003c-e905-4375-91bd-242e74b12277",
        "pageId": "6b1214f0-43e1-447d-b0bb-cf493d361411",
        "language": "en",
        "isPageDetected": true,
        "pageVariantName": "iOSVaraint1",
        "token": "<JWT token placeholder>"
    },
    "plugins": [
        {
            "plugin": {
                "id": "3353172846080032866",
                "name": "dcui",
                "url": "https://wsdk.rokt.com/plugins/dcui/index.html",
                "targetElementSelector": "#target_element",
                "targetElementPosition": "append",
                "targetElementRelation": "child",
                "targetSection": "None",
                "config": {
                    "slots": [
                        {
                            "instanceGuid": "8f492d28-83fb-4813-877e-26e752ea9474",
                            "offer": {
                                "campaignId": "2749386944931233793",
                                "accountId": "106",
                                "maxTotalItemsQtyInOffer": 1,
                                "creative": {
                                    "referralCreativeId": "2760914349384466797",
                                    "instanceGuid": "c9f37d78-731d-4a0e-b8bc-712bd8c46cc1",
                                    "responseOptionsMap": {
                                        "positive": {
                                            "id": "2760914349384466794",
                                            "action": "Url",
                                            "instanceGuid": "1d47ded1-b483-44e6-abf8-1d1d5faa82bc",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "Yes",
                                            "longLabel": "Yes",
                                            "shortSuccessLabel": "Email Sent",
                                            "isPositive": true,
                                            "url": "http://example.com",
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        },
                                        "negative": {
                                            "id": "2760914349384466796",
                                            "action": "CaptureOnly",
                                            "instanceGuid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                                            "signalType": "SignalResponse",
                                            "shortLabel": "No thanks",
                                            "longLabel": "No thanks",
                                            "isPositive": false,
                                            "ignoreBranch": false,
                                            "urlBehavior": "newTab",
                                            "token": "<JWT token placeholder>"
                                        }
                                    },
                                    "links": {
                                        "termsAndConditions": {
                                            "url": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797",
                                            "title": "Terms & Conditions"
                                        }
                                    },
                                    "images": {},
                                    "icons": {},
                                    "token": "<JWT token placeholder>",
                                    "advertiser": {
                                        "name": "000. For Widget Testing",
                                        "brand": "000. For Widget Testing"
                                    },
                                    "copy": {
                                        "creative.copy": "Nicholas Grasevski 2",
                                        "creative.termsAndConditions.message": "Please visit [rokt.com](https://www.rokt.com)for T&Cs",
                                        "creative.termsAndConditions.close.copy": "Close",
                                        "creative.termsAndConditions.title": "Terms & Conditions",
                                        "creative.tag": "B2B Services",
                                        "creative.success.title": "Success",
                                        "creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com.",
                                        "creative.termsAndConditions.link": "https://server-api.rokt.com/LegalTerms/TermsAndConditions/2760914349384466797"
                                    }
                                },
                                "metadata": {}
                            },
                            "layoutVariant": {
                                "layoutVariantId": "3353172846080032865",
                                "moduleName": "standard-marketing",
                                "formatType": "Text",
                                "layoutVariantSchema":"<JSON encoded schema>"
                            },
                            "token": "<JWT token placeholder>"
                        },
                    ],
                    "instanceGuid": "ce5158a9-dc59-4a97-9006-a299901e4587",
                    "outerLayoutSchema": "<JSON encoded schema>",
                    "layoutSchemaVersion": "2.0",
                    "token": "<JWT token placeholder>"
                }
            },
            "fonts": []
        }
    ],
    "options": {
        "useDiagnosticEvents": true
    },
    "success": true
}

Empty Success Response

There is a rare occurrence where there will not be any relevant offers for a particular user. The chances of this occurring can be reduced by providing more attribute data when making the request. In the event of this case, Rokt will return a payload with no experiences:

{
    "sessionId": "b2170028-cf39-4d23-849d-f1c38be50000",
    "pageContext": {
        "pageInstanceGuid": "b2170028-cf39-4ff4-8e7d-d88eb9e441e6",
        "isPageDetected": true,
        "token": "<JWT token placeholder>"
    },
    "plugins": [],
    "options": {
        "useDiagnosticEvents": false
    },
    "token": "<JWT token placeholder>",
    "success": true,
}

Example: Request Validation Error

HTTP Response Code: 422

Click to expand

{
    "title": "Validation failed",
    "status": 422,
    "success": false,
    "errors": [
        {
            "code": "IntegrationNameNotProvided",
            "message": "Integration.Name is required"
        },
        {
            "code": "IntegrationVersionNotProvided",
            "message": "Integration.Version is required"
        },
        {
            "code": "IntegrationFrameworkNotProvided",
            "message": "Integration.Framework is required"
        },
        {
            "code": "IntegrationPlatformInvalid",
            "message": "Integration.Platform is invalid"
        },
        {
            "code": "IntegrationLayoutSchemaVersionNotProvided",
            "message": "Integration.LayoutSchemaVersion is required"
        },
        {
            "code": "IntegrationDeviceLocaleNotProvided",
            "message": "Integration.DeviceLocale is required"
        },
        {
            "code": "IntegrationDeviceModelNotProvided",
            "message": "Integration.DeviceModel is required"
        },
        {
            "code": "IntegrationDeviceTypeNotProvided",
            "message": "Integration.DeviceType is required"
        },
        {
            "code": "IntegrationOperatingSystemNotProvided",
            "message": "Integration.OperatingSystem is required"
        },
        {
            "code": "IntegrationOperatingSystemVersionNotProvided",
            "message": "Integration.OperatingSystemVersion is required"
        },
        {
            "code": "IntegrationPackageNameNotProvided",
            "message": "Integration.PackageName is required"
        },
        {
            "code": "IntegrationPackageVersionNotProvided",
            "message": "Integration.PackageVersion is required"
        },
        {
            "code": "PageIdentifierNotProvided",
            "message": "PageIdentifier is required"
        },
        {
            "code": "PartnerIdNotProvided",
            "message": "rokt-tag-id is missing/incorrect"
        }
    ]
}

HTTP Response Code: 400

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

Internal Server Errors (HTTP 5xx)

In rare circumstances the system may unexpectedly be unable to complete a request, in this case we will return a request without a body and 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 to assist in identifying and correcting the issue.

Caching offers

Rendering Rokt offers in a timely manner allows you to maximize revenue opportunities from user engagement and conversions. However, a server-to-server integration involves extra network calls between Rokt’s backend servers and yours, which delays the retrieval of data necessary for rendering offers.

To aid with performance, we recommend that you fetch offer content from Rokt’s /v2/partner/experiences API endpoint at an earlier point in the user’s transaction journey before our offers are expected to render. It’s best practice to initiate the offer content fetch after a user has demonstrated significant interest in completing the transaction in order to avoid unnecessary network calls.

Once received, the data can be stored in a cache. This will allow faster retrieval later by the client for use within the same transaction.

We recommend caching against a combination of unique and ideally contextual information such as transaction ID, user ID, and user device type. In the scenario of a shifting user context (e.g. from an Android device to an iOS device), the client should fetch new experiences from the /v2/partner/experiences endpoint using updated customer attributes. This ensures that rendered offers remain relevant to the customer’s present context.