SSP Integration Guide

Endpoint

GET  /ssp/:feedId
POST /ssp/:feedId

:feedId is your unique feed identifier provided during onboarding.

---

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
lang	End-user language (ISO 639-1)	en

Optional

Parameter	Description	Example
country	Country code (ISO 3166-1 alpha-2). Auto-detected from IP if omitted.	US
ref	Page URL where the ad will be displayed	https://example.com/page
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
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

---

Request Methods

GET — Query Parameters

Pass all fields as URL query parameters:

GET /ssp/27?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

Code	Meaning
200	Ad found — response body contains the bid
204	No ad available
400	Missing required fields
404	Feed not found or inactive

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/page

Response: 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=en

Response: 204 No Content

(empty body)

Missing Required Fields

Request:

GET /ssp/27?ip=8.8.8.8

Response: 400 Bad Request

{
  "error": "missing required fields: ua, lang"
}

---

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.