Skip to content

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 ​

ParameterDescriptionExample
ipEnd-user IP address8.8.8.8
uaEnd-user User-Agent stringMozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/107.0

Optional ​

ParameterDescriptionExample
keyYour feed key, if one was issueda1b2c3
langEnd-user language (ISO 639-1)en
countryCountry code (ISO 3166-1 alpha-2). Auto-detected from IP if omitted.US
ref or pagePage URL where the ad will be displayedhttps://example.com/page
domainSite domain, if you don't send the page URLexample.com
userid or uidYour user identifieruser-123
pidPublisher identifier42
subid1Sub-tracking ID 1campaign-a
subid2Sub-tracking ID 2placement-b
xffOriginal client IP (if behind proxy/CDN)192.168.1.1,37.179.76.240
bidfloorMinimum price you accept, USD CPM0.5
ch-uaClient Hints: browser brand list"Chrome";v="107"
ch-ua-full-versionClient Hints: full browser version107.0.5304.110
ch-ua-platformClient Hints: OS platformmacOS
ch-ua-platform-versionClient Hints: OS version13.0.1
ch-ua-modelClient Hints: device modelPixel 7
ch-ua-mobileClient 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.com

POST — 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 ​

CodeMeaning
200Ad found — response body contains the bid
204No ad available — also returned for an unknown or inactive feed
400Missing required fields or a malformed request
403Wrong feed key (key)
404The feed id is not a number

Response Format ​

The response format is configured per feed during onboarding. Two common formats:

Format A: Simple JSON ​

json
{
  "ads": [
    {
      "url": "https://tracker.example.com/click?click_id=85aedd2b-84e7-4dfe-9355-87db56e81101",
      "bid": 3.5
    }
  ]
}

Format B: OpenRTB 2.5 ​

json
{
  "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 ​

FieldDescription
url/admClick tracking URL — redirect the user here when they click the ad
bid/priceBid price in USD (CPM)
idUnique 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/page

Response: 200 OK

json
{
  "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=en

Response: 204 No Content

(empty body)

Missing Required Fields ​

Request:

GET /ssp/27?ip=8.8.8.8

Response: 400 Bad Request

json
{
  "error": "missing required fields: ua"
}

Notes ​

  • All prices are in USD.
  • The url / adm field 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.