SSP Integration Guide
Endpoint
GET /ssp/:feedId
POST /ssp/:feedId:feedId— your numeric feed identifier. The host, the feed id and your feed key are provided during onboarding.- Pass your feed key as
key(query parameter) when it was issued to you.
Request Parameters
Required
| Parameter | Description | Example |
|---|---|---|
ip | End-user IP address | 8.8.8.8 |
ua | End-user User-Agent string | Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/107.0 |
Optional
| Parameter | Description | Example |
|---|---|---|
key | Your feed key, if one was issued | a1b2c3 |
lang | End-user language (ISO 639-1) | en |
country | Country code (ISO 3166-1 alpha-2). Auto-detected from IP if omitted. | US |
ref or page | Page URL where the ad will be displayed | https://example.com/page |
domain | Site domain, if you don't send the page URL | example.com |
userid or uid | Your user identifier | user-123 |
pid | Publisher identifier | 42 |
subid1 | Sub-tracking ID 1 | campaign-a |
subid2 | Sub-tracking ID 2 | placement-b |
xff | Original client IP (if behind proxy/CDN) | 192.168.1.1,37.179.76.240 |
bidfloor | Minimum price you accept, USD CPM | 0.5 |
ch-ua | Client Hints: browser brand list | "Chrome";v="107" |
ch-ua-full-version | Client Hints: full browser version | 107.0.5304.110 |
ch-ua-platform | Client Hints: OS platform | macOS |
ch-ua-platform-version | Client Hints: OS version | 13.0.1 |
ch-ua-model | Client Hints: device model | Pixel 7 |
ch-ua-mobile | Client Hints: mobile flag | ?0 |
Client Hints are also accepted under their header names (sec-ch-ua, sec-ch-ua-platform, sec-ch-ua-mobile, …), plus ch-ua-arch, ch-ua-bitness and ch-ua-full-version-list.
Sub-sources (placements). Pass your sub-source id in every request: you get statistics per sub-source, and a weak sub-source can be paused on its own instead of the whole feed. The parameter name is agreed with you at onboarding and configured on your feed.
Timeout. Tell us how long you wait for our answer (your tmax) at onboarding; we set it on your feed and answer within it. If an OpenRTB request carries tmax, that value is used.
Request Methods
GET — Query Parameters
Pass all fields as URL query parameters:
GET /ssp/27?key=YOUR_FEED_KEY&ip=8.8.8.8&ua=Mozilla/5.0%20Chrome/107.0&lang=en&ref=https://example.comPOST — JSON Body
Send a JSON payload. The body format is configured per feed during onboarding.
POST /ssp/27
Content-Type: application/json
{
"device": {
"ip": "5.6.7.8",
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/107.0",
"geo": {
"country": "DE"
},
"language": "de"
}
}POST — XML Body
Same as JSON but with an XML payload. The body format is configured per feed during onboarding.
POST /ssp/27
Content-Type: application/xml
<BidRequest>
<Device>
<IP>5.6.7.8</IP>
<UA>Mozilla/5.0 Chrome/107.0</UA>
</Device>
<Geo>
<Country>DE</Country>
</Geo>
<Language>de</Language>
</BidRequest>Query parameters and body can be combined — body values take precedence, query parameters fill any gaps.
Response
HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Ad found — response body contains the bid |
| 204 | No ad available — also returned for an unknown or inactive feed |
| 400 | Missing required fields or a malformed request |
| 403 | Wrong feed key (key) |
| 404 | The feed id is not a number |
Response Format
The response format is configured per feed during onboarding. Two common formats:
Format A: Simple JSON
{
"ads": [
{
"url": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101",
"bid": 3.5
}
]
}Format B: OpenRTB 2.5
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"seatbid": [
{
"bid": [
{
"id": "85aedd2b-84e7-4dfe-9355-87db56e81101",
"impid": "1",
"price": 3.5,
"adm": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101"
}
]
}
]
}Response Fields
| Field | Description |
|---|---|
url/adm | Click tracking URL — redirect the user here when they click the ad |
bid/price | Bid price in USD (CPM) |
id | Unique bid identifier |
Examples
Successful Request (GET)
Request:
GET /ssp/27?ip=8.8.8.8&ua=Mozilla/5.0%20(Windows%20NT%2010.0)%20Chrome/107.0&lang=en&country=US&ref=https://publisher.com/pageResponse: 200 OK
{
"ads": [
{
"url": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101",
"bid": 3.5
}
]
}No Ad Available
Request:
GET /ssp/27?ip=8.8.8.8&ua=Chrome/107&lang=enResponse: 204 No Content
(empty body)
Missing Required Fields
Request:
GET /ssp/27?ip=8.8.8.8Response: 400 Bad Request
{
"error": "missing required fields: ua"
}Notes
- All prices are in USD.
- The
url/admfield in the response must be used as a redirect URL when the user interacts with the ad. This is required for accurate click tracking and billing. - Country is auto-detected from the IP address if not provided. Passing it explicitly improves accuracy and reduces latency.
- Browser, device type, and OS are automatically detected from the User-Agent string.