Server Offers API Specification
This document outlines the relevant endpoints necessary to interact with Rokt's APIs to retrieve Offer content from 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/offers |
| Testing | POST | https://server-api-demo.rokt.com/v1/partner/offers |
Testing Best PracticeDirect link to Testing Best Practice
The testing endpoint https://server-api-demo.rokt.com/v1/partner/offers 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
Root/BodyDirect link to Root/Body
| Property Name | Required | DataType | Description |
|---|---|---|---|
| pageIdentifier | Yes | string | Text used to differentiate views |
| attributes | Yes | Dictionary<string, string> / Map<string, string> | Contains user attribute data to be used for offer selection. For WebMobile/WebDesktop requests only: Include userAgent (derived from the browser) as an attribute. See example below. |
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 |
| rokt-ui-locale | User Interface culture and country | String | ISO locale and country identifier. e.g. en-US |
| rokt-client-unique-id | For troubleshooting across partner and Rokt systems | String | A reference transaction ID (unique ID) |
| rokt-platform-type | Indicates the platform for which the offers are being requested | string | Default: Mobile Accepted Values: Mobile, Web, WebMobile, WebDesktop |
Additional Required Headers for MobileDirect link to Additional Required Headers for Mobile
When requesting offers for the Mobile platform, the following headers are also required:
| Header-key | Description | Type | Example |
|---|---|---|---|
| rokt-os-type | OS type | string | "iOS" or "Android" |
| rokt-os-version | OS version | String | "8.0" or "4.4.1" |
| rokt-device-model | Device Model for iOS or Build Model for Android | String | "iPhone 6s", "Galaxy S9", etc |
| rokt-package-name | PackageName or BundleIdentifier of host application | String | iOS: com.APPNAME.ios Android: com.APPNAME.android Use the real package name of the given client application |
| rokt-package-version | Package Version or Bundle version of host application | String | 1.0.5 Use the real package version of the given client application |
Request Example (Mobile App)Direct link to Request Example (Mobile App)
JSON Request Body/Payload
{
"attributes": {
"country": "AU",
"firstname": "jenny",
"mobile": "(323) 867-5309",
"postcode": "90210",
"email": "test1593754986316@rokt.com",
"lastname": "Smith"
},
"pageIdentifier": "page_identifier"
}
Request Example (Mobile/Desktop Web)Direct link to Request Example (Mobile/Desktop Web)
JSON Request Body/Payload
{
"attributes": {
"country": "AU",
"firstname": "jenny",
"mobile": "(323) 867-5309",
"postcode": "90210",
"email": "test1593754986316@rokt.com",
"lastname": "Smith",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3.1 Safari/605.1.15"
},
"pageIdentifier": "page_identifier"
}
- userAgent can be derived from the browser, e.g. via
window.navigator.userAgent.
ResponseDirect link to Response
Success Response (200)Direct link to Success Response (200)
Root/BodyDirect link to Root/Body
| Property Name | DataType | Description |
|---|---|---|
| sessionId | string | Rokt Session ID |
| pageInstanceGuid | string | Unique identifier of the user's page instance |
| pageDetectionTime | string | Time at which page detection occurred |
| success | boolean | Indicates whether the request was successful |
| placements | Placement[] | Collection of offers/placement |
PlacementDirect link to Placement
| Property Name | DataType | Description |
|---|---|---|
| experienceId | string | Identifier representing the selected experience from Rokt. If no experience is explicitly selected the value will be NotSet |
| placementGuid | string | A GUID generated which is unique to the placement and to be sent as a part of events calls |
| configurables | Dictionary<string, string> / Map<string, string> | Collection of dynamic parameters used for rendering offers |
| targetingData | TargetingData | Information about why the current set of offers was shown, including advertiser information, for Digital Services Act requirements |
| offers | PartnerOffer[] | Collection of offers to display |
Partner OfferDirect link to Partner Offer
| Property Name | DataType | Description |
|---|---|---|
| creativeId | string | Unique Id for the offer's Creative in the Rokt Platform.1 |
| campaignId | string | Unique Id for the offer's Campaign in the Rokt Platform.1 |
| slotGuid | string | Unique GUID representing the offer slot |
| creativeGuid | string | Unique GUID representing the offer/creative |
| copy | Dictionary<string, string> / Map<string, string> | Collection of KVP used to provide offer data |
| responseOptions | ResponseOption[] | Collection of possible response options |
| advertiser | Advertiser | Details about the advertiser behind this offer |
| formatType | string | Format type to display an offer |
1 The Id will be provided for Ecommerce Campaigns, other campaign types will receive the value: NotSet
CopyDirect link to Copy
| Property Name | DataType | Description |
|---|---|---|
| creative.copy | string | Content of the copy |
| creative.title | string | Title of the copy |
| creative.disclaimer | string | Text of the disclaimer |
| creative.termsAndConditions.link | string | Link to terms and conditions |
| creative.privacyPolicy.link | string | Privacy Policy link |
Response OptionDirect link to Response Option
| Property Name | DataType | Description |
|---|---|---|
| action | string | The action of the response “CaptureOnly” - just fire the event “Url” - The url need to be open and fire the event |
| 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 |
Targeting DataDirect link to Targeting Data
| Property Name | DataType | Description |
|---|---|---|
| link | string | A hyperlink to details on why this selection of offers was shown, including the advertisers' information unique to the session. Displaying this link can support in fulfilling Digital Services Act obligations |
| copy | string | Text displaying how Partners use Rokt to determine the most relevant offers to show customers |
| advertisers | Advertiser[] | The collection of advertisers behind the current set of offers, ordered by the sequence in which the offers are shown |
AdvertiserDirect link to Advertiser
| Property Name | DataType | Description |
|---|---|---|
| name | string | The advertiser's Account Name/Legal Entity |
| brand | string | The advertiser's brand name |
How to find Disclaimer & Terms and ConditionsDirect link to How to find Disclaimer & Terms and Conditions
| Property Name | DataType | Offers Response Location (JSON path) |
|---|---|---|
| Disclaimer | string | body.placements[i].offers[j].copy.creative.disclaimer |
| Terms and Conditions Link | string | body.placements[i].offers[j].copy.creative.termsAndConditions.link |
Where:
- i represents the index of the placement being displayed
- j represents the index of the slot being displayed
ExampleDirect link to Example
{
"sessionId": "aec20020-2d5c-45e7-ac3d-6f5daa22b983",
"pageInstanceGuid": "aec20020-2d5c-4497-87e8-475576ddffa5",
"pageDetectionTime": "2022-06-28T01:57:09.2147413+00:00",
"placements": [
{
"experienceId": "RedButton",
"placementGuid": "8ed27738-fec8-49e4-9436-d44faa6eaf0f",
"targetingData": {
"link": "https://apps-demo.rokt.com/dsa/rokt-en.html?name=Legal%20Name%20One&brand=Brand%20Name%20One&name=Legal%20Name%20Two&brand=Brand%20Name%20Two",
"copy": "Text displaying how Partners use Rokt to determine the most relevant offers to show customers",
"advertisers": [
{
"name": "Legal Name One",
"brand": "Brand Name One"
},
{
"name": "Legal Name Two",
"brand": "Brand Name Two"
}
]
},
"offers": [
{
"creativeId": "NotSet",
"campaignId": "NotSet",
"slotGuid": "58bcbaa0-e13c-4a3d-84cd-2803ccc35394",
"creativeGuid": "b3a1d523-5490-49f0-a379-7a67628a4cdd",
"copy": {
"creative.copy": "This is an Rokt Commerce Email Campaign from Mobile team Account. This should appear in prime position for the mobile SDK automated testing. ",
"creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732356166940819466",
"creative.termsAndConditions.close.copy": "Close",
"creative.termsAndConditions.title": "Terms of Use",
"creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732356166940819466",
"creative.privacyPolicy.close.copy": "Close",
"creative.privacyPolicy.title": "Privacy Policy",
"creative.confirmation.message": "Details will go to test1593754986316@rokt.com",
"creative.success.title": "Success",
"creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com."
},
"advertiser": {
"name": "Legal Name One",
"brand": "Brand Name One"
}
"responseOptions": [
{
"action": "CaptureOnly",
"responseOptionGuid": "6bea8e29-b3cd-4717-bd82-59ccbca0d863",
"signalType": "SignalResponse",
"label": "Yes",
"successText": "Subscribed",
"isPositive": true,
"url": ""
},
{
"action": "CaptureOnly",
"responseOptionGuid": "04c74a56-9fa7-408e-b722-052ae275f53f",
"signalType": "SignalResponse",
"label": "No thanks",
"successText": "",
"isPositive": false,
"url": ""
}
],
"formatType": "Text"
},
{
"creativeId": "2732357120423559183",
"campaignId": "2732344566234284034",
"slotGuid": "e499763e-769e-4621-8591-c55c6b833e1f",
"creativeGuid": "11096aa6-878f-4bb7-acb5-156d0999edb8",
"copy": {
"creative.disclaimer": "<strong>Disclaimer</strong>",
"creative.copy": "This is an acquire email campaign from Mobile team Account for mobile SDK automated testing.",
"creative.termsAndConditions.link": "https://server-api-demo.rokt.com/LegalTerms/TermsAndConditions/2732357120423559183",
"creative.termsAndConditions.close.copy": "Close",
"creative.termsAndConditions.title": "Terms & Conditions",
"creative.privacyPolicy.link": "https://server-api-demo.rokt.com/LegalTerms/PrivacyPolicy/2732357120423559183",
"creative.privacyPolicy.close.copy": "Close",
"creative.privacyPolicy.title": "Privacy Policy",
"creative.confirmation.message": "Confirmation will go to test1593754986316@rokt.com",
"creative.success.title": "Success",
"creative.success.copy": "We have sent a confirmation to test1593754986316@rokt.com."
},
"advertiser": {
"name": "Legal Name Two",
"brand": "Brand Name Two"
},
"responseOptions": [
{
"action": "CaptureOnly",
"responseOptionGuid": "779e41cd-5653-4143-b0bb-3df4eb3a2325",
"signalType": "SignalResponse",
"label": "Yes please",
"successText": "Email Sent",
"isPositive": true,
"url": ""
},
{
"action": "CaptureOnly",
"responseOptionGuid": "87af7302-0c53-4676-a002-8f0f8fcbb530",
"signalType": "SignalResponse",
"label": "No thanks",
"successText": "",
"isPositive": false,
"url": ""
}
],
"formatType": "Text"
}
],
"configurables": {
"positive.button.color": "red"
}
}
],
"success": true
}
Empty Success Response (200)Direct link to Empty Success Response (200)
There is a rare occurrence where there will not be any relevant offers for a particular user. In this case, Rokt will return a payload with no placements:
{
"sessionId": "aec20024-8d23-46be-95f3-9be5d86292a9",
"pageInstanceGuid": "aec20024-8d24-4ee5-8b6b-2b45364e678b",
"pageDetectionTime": "2022-06-28T02:13:04.7608276+00:00",
"placements": [],
"success": true
}
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 |
ErrorDirect link to Error
| Property Name | DataType | Description |
|---|---|---|
| code | string | Corresponding error code |
| message | number | Message describing the error |
| value | boolean | Provided value that was invalid, if any |
Example: Request Validation Error (422)Direct link to Example: Request Validation Error (422)
{
"title": "Validation failed",
"status": 422,
"success": false,
"errors": [
{
"code": "PartnerIdNotIncluded",
"message": "rokt-tag-id is missing/incorrect",
"value": "0"
},
{
"code": "NotEmptyValidator",
"message": "Missing header: rokt-os-type."
},
{
"code": "NotEmptyValidator",
"message": "Missing header: rokt-package-name."
},
{
"code": "NotEmptyValidator",
"message": "Missing header: rokt-package-version."
},
{
"code": "NotEmptyValidator",
"message": "Missing header: rokt-device-model."
},
{
"code": "NotEmptyValidator",
"message": "Missing header: rokt-sdk-version."
},
{
"code": "NotEmptyValidator",
"message": "Missing header: rokt-os-version."
},
{
"code": "ClientUniqueIdIsMissing",
"message": "Missing header: rokt-client-unique-id."
},
{
"code": "PlatformTypeIsInvalid",
"message": "Invalid header: rokt-platform-type."
}
]
}
Example: Empty RequestDirect link to Example: Empty Request
{
"title": "BadRequest",
"status": 400,
"success": false,
"errors": [
{
"code": "InvalidRequestPayload",
"message": "Request body format is not valid"
}
]
}
Example: Too Many Requests (429)Direct link to Example: Too Many Requests (429)
Rokt may throttle or temporarily block traffic to protect platform stability or enforce policy. In these cases, the API returns HTTP 429 with an empty body and no Retry-After header. Please do not retry these requests — automated retries can increase load and prolong throttling. Pause further calls for this flow, review your request rate, and contact your Rokt representative if 429s persist.
Internal Service Errors (5XX)Direct link to Internal Service Errors (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.
Caching offersDirect link to 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 /offers 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 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 placements from the /offers endpoint using updated customer attributes. This ensures that rendered offers remain relevant to the customer’s present context.