Session API (2.0.0)
The Rokt Session API is a server-to-server integration for requesting offers and reporting the events that follow. It replaces client-side placement of the Rokt SDK for partners who prefer to render offers themselves.
A Session API integration has two calls:
- Offers — send transaction and customer context, receive the offer to render.
- Events — report what happened to that offer: impressions, viewability, customer responses, and dismissals.
The events call is not optional. Rokt bills and optimizes on the events you report, so an integration that renders offers without reporting impressions and responses will under-report performance and earn less.
For an end-to-end walkthrough, see Session API integration (S2S).
Every request carries two things:
Authorization: Basic base64(rpub:rsec)— your public and secret API keys, joined with a colon and base64-encoded.rokt-account-id— your Rokt account ID.
Your Rokt account team provides all three values. Treat the secret key as a credential: keep it server-side and never ship it to a browser or mobile app.
There is no separate sandbox host. To validate an integration before going
live, send rokt-test-session: true on the production endpoint. Test sessions
are tagged and excluded from production reporting.
The header affects reporting only — it does not force an offer to serve. For deterministic end-to-end testing, your account team can configure a staging page with dedicated test campaigns. Remove the header to go live.
Requests may be throttled. A throttled request returns 429 and is safe to
retry, but do not retry automatically in a tight loop — back off, and contact
your Rokt representative if 429s persist.
Request the offers to render for a transaction.
Called once per page view, with whatever customer and transaction context you can supply — the richer the context, the better the offer. The response carries the session and page identifiers you echo back when reporting events, so keep them for the lifetime of the transaction.
Request offers
Returns the offers to render for a transaction, along with the session identifiers you will echo back on the events call.
An empty plugins array is a normal, successful outcome. When there
is no relevant offer for a customer, Rokt returns 200 with plugins: [].
Render nothing and continue your page — this represents a real share of
production traffic and is not an error.
Caching
To maximize revenue, request offers earlier in the customer's journey than the point where you intend to render them, and cache the response for fast retrieval within the same transaction. Cache against a combination of transaction ID, customer ID, and device type. If the customer context changes — a device switch, for example — request again with the updated attributes so the offer stays relevant.
Authorizations:
header Parameters
| rokt-account-id required | string Example: 2748881613004506238 Your Rokt account ID. Required on every call. |
| rokt-platform-type | string Enum: "iOS" "Android" "Web" "WebDesktop" "WebMobile" Example: Web The platform the offers are being requested for. Case-insensitive;
defaults to Server-to-server traffic classifies as Web by default. If your Rokt pages are configured for a native platform, set this header to match — otherwise page detection will not match your native-configured pages and no offers will be returned. Web-configured pages need no header. |
| rokt-test-session | boolean Example: true Marks the session as a test. Test sessions are tagged and excluded from production reporting. Reporting only — it does not force an offer to serve. Remove to go live. |
Request Body schema: application/jsonrequired
required | object (Channel) Identifies the integration type. Server-to-server callers send |
required | object (Page) |
object (Customer) | |
object (Transaction) | |
object (Payment) | |
object (Device) | |
object Free-form string map for partner-specific signals that do not fit a typed object. Send only values you own. Geo, demographics, device type and OS, payment method, and modeled signals are derived by Rokt and will be overwritten if sent. |
Responses
Request samples
- Payload
{- "channel": {
- "type": "s2s"
}, - "page": {
- "page_identifier": "checkout"
}, - "customer": {
- "email": "jane.doe@example.com",
- "first_name": "Jane",
- "last_name": "Doe",
- "postal_code": "10001",
- "language": "en"
}, - "transaction": {
- "transaction_value": 19.99,
- "currency": "USD",
- "confirmation_ref": "ORDER-000123"
}, - "payment": {
- "type": "card"
}, - "device": {
- "user_agent": "YourApp/1.0 (mobile)"
}, - "attributes": {
- "your_custom_attribute": "value"
}
}Response samples
- 200
- 400
- 401
- 429
- 500
{- "session_id": "b1fb003c-e904-4083-b7b9-03cde555a7a1",
- "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
- "session_token": {
- "token": "<session_token>"
}, - "plugins": [
- {
- "plugin": {
- "id": "3353172846080032866",
- "name": "dcui",
- "config": {
- "instance_guid": "ce5158a9-dc59-4a97-9006-a299901e4587",
- "slots": [
- {
- "instance_guid": "8f492d28-83fb-4813-877e-26e752ea9474",
- "token": "<event-token>",
- "offer": {
- "campaign_id": "2749386944931233793",
- "creative": {
- "instance_guid": "c9f37d78-731d-4a0e-b8bc-712bd8c46cc1",
- "token": "<event-token>",
- "advertiser": {
- "name": "Example Advertiser Inc.",
- "brand": "Example Brand"
}, - "copy": {
- "creative.title": "Get 20% off your next order",
- "creative.disclaimer": "New customers only. Terms apply.",
}, - "response_options_map": {
- "positive": {
- "instance_guid": "1d47ded1-b483-44e6-abf8-1d1d5faa82bc",
- "short_label": "Yes",
- "long_label": "Yes please",
- "is_positive": true,
- "action": "Url",
- "url_behavior": "newTab",
- "token": "<event-token>"
}, - "negative": {
- "instance_guid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
- "short_label": "No thanks",
- "long_label": "No thanks",
- "is_positive": false,
- "action": "CaptureOnly",
- "token": "<event-token>"
}
}
}
}
}
]
}
}
}
]
}
Report what happened to the offers you rendered.
Rokt bills and optimizes on these events, so an integration that renders offers without reporting impressions and responses will under-report its own performance and earn less. Events are sent in batches and can partially succeed, so check the per-event results rather than the status code alone.
Report events
Reports what happened to the offers returned by the offers call: impressions, viewability, customer responses, and dismissals.
Each event points at the element it describes using data.parent_id and
data.token, both taken verbatim from the offers response. Send
single_session: true and set each event's session_id to the
session_id you received.
Events are accepted in batches, and a batch can partially succeed — see
the 202 response.
Authorizations:
header Parameters
| rokt-account-id required | string Example: 2748881613004506238 Your Rokt account ID. Required on every call. |
| rokt-test-session | boolean Example: true Marks the session as a test. Test sessions are tagged and excluded from production reporting. Reporting only — it does not force an offer to serve. Remove to go live. |
Request Body schema: application/jsonrequired
required | object (Channel) Identifies the integration type. Server-to-server callers send |
| single_session required | boolean Send |
required | Array of objects (Event) non-empty |
Responses
Request samples
- Payload
Send one per rendered element, using that element's own
instance_guid as parent_id and its own token.
{- "channel": {
- "type": "s2s"
}, - "single_session": true,
- "events": [
- {
- "event_type": "impression",
- "instance_id": "018f1234-5678-7abc-8def-0123456789ab",
- "session_id": "018f2a1b-2222-7abc-8def-session00001",
- "timestamp": 1751234567000,
- "data": {
- "parent_id": "018f2a1b-3333-7abc-8def-creative001",
- "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
- "token": "<event-token>",
- "capture_method": "ClientProvided"
}
}
]
}Response samples
- 202
- 400
- 401
- 429
- 500
{- "session_token": {
- "token": "<session_token>"
}, - "event_ids": [
- "018f9c40-1a2b-7abc-8def-eventimpression",
- "018f9c40-1a2b-7abc-8def-eventresponse01"
], - "errors": [ ],
- "warnings": [ ]
}