SSP request integration

Request endpoint

POST /openrtb/{ssp_id}
Content-Type: application/json

Agree the actual hostname and identity during onboarding. https://exchange.example.com is illustrative only. SSP ID contains 1–128 ASCII bytes from letters, digits, dot, underscore, and hyphen (A-Z a-z 0-9 . _ -). Extra path segments, percent encoding, a trailing slash, and query strings are not accepted. /bid is not an alias.

Identity comes from this path and configured authentication, not the JSON body, Host, Cookie, or X-Forwarded-*. Proxies must preserve the signed path exactly: do not re-encode it, append a query, or reconstruct a different identity from forwarding headers.

HTTP and authentication

HTTP and HTTPS use the same authentication rules. The inbound protocol does not require HTTPS or force an HTTPS redirect. HTTPS is recommended according to the parties’ transport-security requirements. HMAC authenticates metadata, not the body: an interceptor on a cleartext connection can replace the body and race the original request. Nonce deduplication is not body protection.

• Send exactly one Content-Type header with application/json; a charset parameter is allowed.
• Send uncompressed JSON. Omit Content-Encoding or use identity; gzip and other compression are unsupported.
• New integrations send the four unique headers described in HMAC authentication.
• Only an SSP explicitly configured for the older legacy-token-v1 profile uses a single Authorization: Bearer <token>. An HMAC SSP cannot fall back to its old bearer token.
• The SSP body limit is 256 KiB (262144 bytes), based on actual bytes read. The outbound request is checked against the same limit after fields are added or rewritten.

Minimal Banner request

{
  "id": "example-request-banner",
  "at": 1,
  "tmax": 100,
  "cur": ["USD"],
  "imp": [
    {
      "id": "example-imp-1",
      "banner": { "w": 320, "h": 50 },
      "bidfloor": 1.5,
      "bidfloorcur": "USD"
    }
  ],
  "app": { "bundle": "com.example.app" },
  "device": { "os": "Android", "geo": { "country": "USA" } }
}

The 100 is an example request budget, not a latency promise. Download the Banner request, Video request, and Native request.

Required structure

id and imp[0].id are 1–128-byte strings, not whitespace-only and without control characters. at must explicitly be the integer 1; the OpenRTB second-price default is not reinterpreted as first price. Send exactly one impression, one media object, and one App / Site source. Duplicate JSON keys are rejected at every level, including keys that become identical after unescaping.

tmax is optional; when present it must be an integer from 1 to 60000 milliseconds. The overall deadline starts when request handling begins and includes authentication, body reading, parsing, decisions, and downstream requests. The effective budget is also constrained by the service limit and DSP timeout. The service’s default total budget is 120 ms, but deployments can configure it differently; confirm the applicable budget rather than treating the default as an SLA. A body-read timeout may return 408; no eligible bid within the business deadline returns 204.

Country and platform dimensions may be omitted but must be valid when present. Valid uppercase ISO alpha-2 / alpha-3 country codes become alpha-2 for matching; OS becomes ASCII lowercase for matching. App Bundle is an exact, case-sensitive string. This normalization is for matching, not a rewrite of the original forwarded fields.

See the field reference for the full matrix and responses for retry handling.

Protocol and implementation checked: 2026-09-21.