Bid - Thrad DSP API Documentation

{
  "id": "auction_987654321",
  "at": 1,
  "tmax": 2000,
  "cur": ["USD"],
  "test": 0,
  "site": {
    "id": "pub_42",
    "domain": "yourchatbot.com",
    "page": "https://yourchatbot.com/chat",
    "cat": ["596"],
    "cattax": 7,
    "search": "best crm tools for 10 person startup",
    "keywords": "crm, software, startup, b2b",
    "publisher": { "id": "pub_42", "name": "Your Chatbot", "domain": "yourchatbot.com" }
  },
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "ip": "192.168.1.1",
    "devicetype": 2,
    "os": "OSX",
    "geo": { "country": "USA", "region": "CA", "city": "San Francisco", "type": 2 },
    "language": "en"
  },
  "user": {
    "id": "hashed_user_id_xyz987",
    "ext": { "consent": "<TCF v2 string when GDPR applies>" }
  },
  "regs": { "gdpr": 0, "us_privacy": "1---" },
  "source": {
    "fd": 0,
    "tid": "auction_987654321",
    "ext": { "schain": { "complete": 1, "ver": "1.0", "nodes": [
      { "asi": "ssp.thrads.ai", "sid": "pub_42", "hp": 1 }
    ]}}
  },
  "imp": [{
    "id": "1",
    "tagid": "sponsored_message_image_v1",
    "secure": 1,
    "bidfloor": 4.00,
    "bidfloorcur": "USD",
    "native": {
      "request": "{\"ver\":\"1.2\",\"context\":1,\"contextsubtype\":10,\"plcmttype\":4,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":90}},{\"id\":2,\"required\":1,\"data\":{\"type\":2,\"len\":200}},{\"id\":3,\"required\":1,\"data\":{\"type\":1,\"len\":50}},{\"id\":4,\"required\":0,\"img\":{\"type\":3,\"wmin\":400,\"hmin\":400,\"mimes\":[\"image/jpeg\",\"image/png\",\"image/webp\"]}},{\"id\":5,\"required\":0,\"img\":{\"type\":1,\"wmin\":100,\"hmin\":100,\"mimes\":[\"image/jpeg\",\"image/png\",\"image/webp\"]}},{\"id\":6,\"required\":1,\"data\":{\"type\":12,\"len\":15}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1]}],\"privacy\":1}"
    },
    "ext": {
      "thrad": {
        "chat_id": "chat_456",
        "n_ads_before": 2,
        "prefetched": true,
        "request_type": "sponsored_message"
      }
    }
  }]
}

{
  "id": "auction_987654321",
  "cur": "USD",
  "seatbid": [{
    "seat": "your-dsp",
    "bid": [{
      "id": "bid_abc123",
      "impid": "1",
      "price": 7.50,
      "adm": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"title\":{\"text\":\"Best CRM for startups\"}},{\"id\":2,\"data\":{\"value\":\"Try HubSpot free for 30 days.\"}},{\"id\":3,\"data\":{\"value\":\"HubSpot\"}},{\"id\":4,\"img\":{\"url\":\"https://your-dsp.com/img/hero.jpg\",\"w\":1200,\"h\":627}},{\"id\":5,\"img\":{\"url\":\"https://your-dsp.com/img/logo.png\",\"w\":100,\"h\":100}},{\"id\":6,\"data\":{\"value\":\"Try Free\"}}],\"link\":{\"url\":\"https://your-dsp.com/click/abc123?price=${AUCTION_PRICE}\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://your-dsp.com/imp/abc123\"}]}}",
      "adomain": ["hubspot.com"],
      "crid": "creative_42",
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "lurl": "https://your-dsp.com/loss?bid=${AUCTION_BID_ID}&reason=${AUCTION_LOSS}",
      "burl": "https://your-dsp.com/billed?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}"
    }]
  }]
}

{
  "id": "auction_987654321",
  "at": 1,
  "tmax": 2000,
  "cur": ["USD"],
  "test": 0,
  "site": {
    "id": "pub_42",
    "domain": "yourchatbot.com",
    "page": "https://yourchatbot.com/chat",
    "cat": ["596"],
    "cattax": 7,
    "search": "best crm tools for 10 person startup",
    "keywords": "crm, software, startup, b2b",
    "publisher": { "id": "pub_42", "name": "Your Chatbot", "domain": "yourchatbot.com" }
  },
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "ip": "192.168.1.1",
    "devicetype": 2,
    "os": "OSX",
    "geo": { "country": "USA", "region": "CA", "city": "San Francisco", "type": 2 },
    "language": "en"
  },
  "user": {
    "id": "hashed_user_id_xyz987",
    "ext": { "consent": "<TCF v2 string when GDPR applies>" }
  },
  "regs": { "gdpr": 0, "us_privacy": "1---" },
  "source": {
    "fd": 0,
    "tid": "auction_987654321",
    "ext": { "schain": { "complete": 1, "ver": "1.0", "nodes": [
      { "asi": "ssp.thrads.ai", "sid": "pub_42", "hp": 1 }
    ]}}
  },
  "imp": [{
    "id": "1",
    "tagid": "sponsored_message_image_v1",
    "secure": 1,
    "bidfloor": 4.00,
    "bidfloorcur": "USD",
    "native": {
      "request": "{\"ver\":\"1.2\",\"context\":1,\"contextsubtype\":10,\"plcmttype\":4,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":90}},{\"id\":2,\"required\":1,\"data\":{\"type\":2,\"len\":200}},{\"id\":3,\"required\":1,\"data\":{\"type\":1,\"len\":50}},{\"id\":4,\"required\":0,\"img\":{\"type\":3,\"wmin\":400,\"hmin\":400,\"mimes\":[\"image/jpeg\",\"image/png\",\"image/webp\"]}},{\"id\":5,\"required\":0,\"img\":{\"type\":1,\"wmin\":100,\"hmin\":100,\"mimes\":[\"image/jpeg\",\"image/png\",\"image/webp\"]}},{\"id\":6,\"required\":1,\"data\":{\"type\":12,\"len\":15}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1]}],\"privacy\":1}"
    },
    "ext": {
      "thrad": {
        "chat_id": "chat_456",
        "n_ads_before": 2,
        "prefetched": true,
        "request_type": "sponsored_message"
      }
    }
  }]
}

{
  "id": "auction_987654321",
  "cur": "USD",
  "seatbid": [{
    "seat": "your-dsp",
    "bid": [{
      "id": "bid_abc123",
      "impid": "1",
      "price": 7.50,
      "adm": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"title\":{\"text\":\"Best CRM for startups\"}},{\"id\":2,\"data\":{\"value\":\"Try HubSpot free for 30 days.\"}},{\"id\":3,\"data\":{\"value\":\"HubSpot\"}},{\"id\":4,\"img\":{\"url\":\"https://your-dsp.com/img/hero.jpg\",\"w\":1200,\"h\":627}},{\"id\":5,\"img\":{\"url\":\"https://your-dsp.com/img/logo.png\",\"w\":100,\"h\":100}},{\"id\":6,\"data\":{\"value\":\"Try Free\"}}],\"link\":{\"url\":\"https://your-dsp.com/click/abc123?price=${AUCTION_PRICE}\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://your-dsp.com/imp/abc123\"}]}}",
      "adomain": ["hubspot.com"],
      "crid": "creative_42",
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "lurl": "https://your-dsp.com/loss?bid=${AUCTION_BID_ID}&reason=${AUCTION_LOSS}",
      "burl": "https://your-dsp.com/billed?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}"
    }]
  }]
}

The endpoint URL is yours — configure it with the Thrad team during onboarding.

Authentication

Authorization

string

required

Bearer <your-shared-key> — provided by you at onboarding.

BidRequest
BidResponse

Envelope

string

required

Auction id. Echo in BidResponse.id.

integer

required

Always 1 — first-price.

tmax

integer

required

Always 2000 ms. Responses after this are dropped.

cur

string[]

required

Always ["USD"].

test

integer

required

1 during onboarding, 0 in production.

`imp[]`

Always a single impression.

imp[].id

string

required

Always "1".

imp[].tagid

string

required

Slot identifier. Encodes both format and render mode — key your bid multipliers, frequency caps, and creative eligibility off this. One of:

tagid	Format	Mode	DSP must populate
`sponsored_message_image_v1`	In-conversation	Image preferred (logo also accepted)	Asset 4 (image) or asset 5 (icon)
`sponsored_message_text_v1`	In-conversation	Text only — image will be rejected server-side	Asset 5 (icon/logo) — required
`opener_image_v1`	Pre-chat opener	Image preferred (logo also accepted)	Asset 4 (image) or asset 5 (icon)
`opener_text_v1`	Pre-chat opener	Text only — image will be rejected server-side	Asset 5 (icon/logo) — required

Bumps to _vN only happen when the slot’s creative contract changes in a way that breaks existing creatives.

imp[].bidfloor

float

required

Floor in CPM USD.

imp[].bidfloorcur

string

required

Always "USD".

Fields Thrad intentionally does not send:

imp[].pos — none of the oRTB position enums (above-fold, full-screen, etc.) cleanly describe inline chatbot inventory. Route on imp[].tagid and the Native asset list instead.
imp[].battr — the Native 1.2 asset shape Thrad requests already structurally rejects video, audio, expandable, and pop creatives. Sending battr would be noise on top.

imp[].secure

integer

required

Always 1. All URLs in your response must be HTTPS.

imp[].native.ver

string

required

Always "1.2" (outer ver double-declaration). The inner native.request envelope also carries ver: "1.2".

imp[].native.request

string

required

JSON-encoded Native 1.2 request object. Shape forks by render mode (signalled in imp[].tagid) — the publisher’s image_enabled config drives both the tagid and the asset list, so they’re always consistent.Image mode (tagid ends in _image_v1) — accepts both image and text creatives:

{
  "native": {
    "ver": "1.2",
    "context": 1,
    "contextsubtype": 10,
    "plcmttype": 4,
    "plcmtcnt": 1,
    "assets": [
      { "id": 1, "required": 1, "title": { "len": 90 } },
      { "id": 2, "required": 1, "data": { "type": 2, "len": 200 } },
      { "id": 3, "required": 1, "data": { "type": 1, "len": 50 } },
      { "id": 4, "required": 0, "img": { "type": 3, "wmin": 400, "hmin": 400, "mimes": ["image/jpeg", "image/png", "image/webp"] } },
      { "id": 5, "required": 0, "img": { "type": 1, "wmin": 100, "hmin": 100, "mimes": ["image/jpeg", "image/png", "image/webp"] } },
      { "id": 6, "required": 1, "data": { "type": 12, "len": 15 } }
    ],
    "eventtrackers": [{ "event": 1, "methods": [1] }],
    "privacy": 1
  }
}

Text mode (tagid ends in _text_v1) — publisher cannot render images. Asset 4 is omitted entirely and asset 5 (logo) becomes required:

"assets": [
  { "id": 1, "required": 1, "title": { "len": 90 } },
  { "id": 2, "required": 1, "data": { "type": 2, "len": 200 } },
  { "id": 3, "required": 1, "data": { "type": 1, "len": 50 } },
  { "id": 5, "required": 1, "img": { "type": 1, "wmin": 100, "hmin": 100, "mimes": ["image/jpeg", "image/png", "image/webp"] } },
  { "id": 6, "required": 1, "data": { "type": 12, "len": 15 } }
]

Required assets in both modes: 1 (title), 2 (description), 3 (sponsoredBy), 6 (CTA). Bids missing any of these are rejected.Asset 5 (logo): required in text mode, optional in image mode.Asset 4 (main image): only present (and only acceptable in your response) in image mode. If you return image_url on a text-mode request, the SSP drops it server-side before render — a logo-only creative will still serve, but if you sent neither asset 5 nor a usable image, the bid is silently lost. Always honour the tagid signal.title.len is parameterised by the publisher’s max_headline_chars setting (≥ 30, default 90). The other len values and image dimensions are global per format. len is a maximum character count; wmin/hmin are minimum image dimensions in pixels.

imp[].ext.thrad

object

Thrad extension — conversation-level signals that do not fit any standard oRTB field. Lives under ext so spec-strict bidders can ignore it cleanly; none of these affect SSP-side auction logic, they’re hints your DSP can use for creative selection or pacing.

Show fields

chat_id

string

Conversation id. Stable across turns within the same chat. Omitted on opener (no chat exists yet).

n_ads_before

integer

Number of ads already served earlier in this conversation. Useful for frequency capping and creative rotation.

prefetched

boolean

true if the request was issued speculatively before the assistant’s reply is shown to the user. Prefetched impressions still bill normally on render confirmation.

request_type

string

Either "opener" (pre-chat slot) or "sponsored_message" (in-conversation slot). Mirrors imp[].tagid and lets you key creative rules without parsing the tag string.

`site` / `app`

Exactly one of site or app is present per request. app ships when the publisher’s inventory is in-app (ios_app / android_app); otherwise site. The publisher subblock is identical in both.

site.id

string

required

Opaque publisher slot id. Resolved in priority: (1) per-DSP external_site_id override if your DSP requires a fixed id (set at onboarding), (2) the chatbot’s public_id (UUID), (3) stringified internal publisher id (legacy fallback). Stable for a given chatbot.

site.domain

string

Hostname where the chatbot is rendered (lowercased, scheme stripped). Derived from the publisher’s per-request URL. Omitted when the publisher doesn’t provide a URL.

site.page

string

Full page URL where the chatbot is rendered. Omitted when not provided.

site.privacypolicy

integer

required

Always 1. The Thrad network operates under a privacy policy.

site.publisher.id

string

required

Opaque publisher organisation id. Resolved in priority: (1) per-DSP external_site_id override, (2) the organisation’s public_id (UUID), (3) stringified internal publisher id. Equals site.id when override (1) is in play; differs otherwise.

site.publisher.name

string

Organisation name, lowercased. Adtech allow/denylists key on string equality — we normalise upstream so you don’t have to. Omitted when unset.

site.publisher.domain

string

Organisation domain, lowercased, scheme + path stripped. Omitted when unset. Different concept from site.domain — this is the publisher organisation’s domain (sellers.json target once Wave 4 ships); site.domain is where the ad runs.

site.cat

string[]

IAB Content Taxonomy 3.0 Tier 1 Unique ID. Always paired with site.cattax: 7. IDs are mostly numeric (e.g. "1" Automotive, "483" Sports, "596" Technology & Computing) but six are short alphanumeric extension IDs ("JLBCU7" Entertainment, "8VZQHL" Events, "SPSHQ5" Genres, "1KXCLD" Holidays, "v9i3On" Sensitive Topics). Sub-tiers are not currently signalled.

site.cattax

integer

Always 7 (IAB Content Taxonomy 3.0). Present alongside site.cat.

site.search

string

LLM-rephrased conversational query. Primary intent signal.

site.keywords

string

Comma-separated topical keywords.

`app` block (in-app inventory only)

Same id / publisher / cat / cattax / search / keywords semantics as site. Additionally:

app.bundle

string

iOS bundle ID (com.example.app) or Android package name. Required for in-app inventory.

app.storeurl

string

App Store / Play Store listing URL.

app.domain

string

App marketing site domain — reuses the publisher organisation’s domain (same value as app.publisher.domain).

`device`

device.ua

string

required

End-user User-Agent.

device.ip

string

End-user IPv4. Omitted when the user is on IPv6 (see device.ipv6).

device.ipv6

string

End-user IPv6. Sent instead of device.ip when applicable.

device.devicetype

integer

required

2=desktop, 4=phone, 5=tablet, 0 for unknown.

device.js

integer

required

Always 1. Thrad’s chatbot widget is JS-rendered — noscript fallbacks are never needed.

device.language

string

ISO 639-1 alpha-2. Priority: (1) conversation language auto-detected from messages (best for in-chat ads), (2) Accept-Language header parsed from the publisher request (fallback for openers and sparse conversations). Field is omitted entirely when neither signal is available.

device.geo.country

string

ISO-3 country code.

device.geo.region

string

Region/state, when available.

device.geo.city

string

City, when available.

device.geo.type

integer

Always 2 (IP-based) when the geo block is present. Thrad does not collect GPS-grade geolocation.

device.os

string

OS string, UA-parsed.

device.ifa

string

Advertising id (IDFA/GAID). In-app only.

device.dnt

integer

1 if Do Not Track.

device.lmt

integer

1 if Limit Ad Tracking.

`user`

user.id

string

required

Anonymous Thrad user id.

user.buyeruid

string

DSP cookie-match value, when available via cookie sync.

user.keywords

string

Mirrors imp[].ext.thrad.keywords.

IAB TCF v2.x consent string. Present when regs.gdpr=1.

`regs`

Currently always 0 — a deliberate stub. Thrad SSP does not yet thread TCF consent strings through from publishers (full consent block is on the Wave 4 roadmap). Explicit 0 is honest (“not operating under GDPR yet”) and unblocks DSPs that gate eligibility on regs.gdpr being declared; bidding on EU/UK traffic without a consent string is at your discretion.

regs.us_privacy

string

CCPA string, when supplied by the publisher. Not yet wired — Wave 4.

regs.gpp

string

GPP string, when supplied by the publisher. Not yet wired — Wave 4.

regs.coppa

integer

1 if user is flagged under-13. Not yet wired — Wave 4.

`source`

source.fd

integer

required

Always 0. SSP is the entity making the auction decision.

source.tid

string

required

Transaction id. Echoes BidRequest.id.

source.ext.schain

object

IAB SupplyChain object (sellers.json chain). Not yet sent — Wave 4 (depends on the publisher public_id work).

`bcat` / `badv`

bcat

string[]

Blocked IAB categories. Only present when set.

badv

string[]

Blocked advertiser domains. Only present when set.

{
  "id": "auction_987654321",
  "at": 1,
  "tmax": 2000,
  "cur": ["USD"],
  "test": 0,
  "site": {
    "id": "pub_42",
    "domain": "yourchatbot.com",
    "page": "https://yourchatbot.com/chat",
    "cat": ["596"],
    "cattax": 7,
    "search": "best crm tools for 10 person startup",
    "keywords": "crm, software, startup, b2b",
    "publisher": { "id": "pub_42", "name": "Your Chatbot", "domain": "yourchatbot.com" }
  },
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "ip": "192.168.1.1",
    "devicetype": 2,
    "os": "OSX",
    "geo": { "country": "USA", "region": "CA", "city": "San Francisco", "type": 2 },
    "language": "en"
  },
  "user": {
    "id": "hashed_user_id_xyz987",
    "ext": { "consent": "<TCF v2 string when GDPR applies>" }
  },
  "regs": { "gdpr": 0, "us_privacy": "1---" },
  "source": {
    "fd": 0,
    "tid": "auction_987654321",
    "ext": { "schain": { "complete": 1, "ver": "1.0", "nodes": [
      { "asi": "ssp.thrads.ai", "sid": "pub_42", "hp": 1 }
    ]}}
  },
  "imp": [{
    "id": "1",
    "tagid": "sponsored_message_image_v1",
    "secure": 1,
    "bidfloor": 4.00,
    "bidfloorcur": "USD",
    "native": {
      "request": "{\"ver\":\"1.2\",\"context\":1,\"contextsubtype\":10,\"plcmttype\":4,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":90}},{\"id\":2,\"required\":1,\"data\":{\"type\":2,\"len\":200}},{\"id\":3,\"required\":1,\"data\":{\"type\":1,\"len\":50}},{\"id\":4,\"required\":0,\"img\":{\"type\":3,\"wmin\":400,\"hmin\":400,\"mimes\":[\"image/jpeg\",\"image/png\",\"image/webp\"]}},{\"id\":5,\"required\":0,\"img\":{\"type\":1,\"wmin\":100,\"hmin\":100,\"mimes\":[\"image/jpeg\",\"image/png\",\"image/webp\"]}},{\"id\":6,\"required\":1,\"data\":{\"type\":12,\"len\":15}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1]}],\"privacy\":1}"
    },
    "ext": {
      "thrad": {
        "chat_id": "chat_456",
        "n_ads_before": 2,
        "prefetched": true,
        "request_type": "sponsored_message"
      }
    }
  }]
}

Envelope

string

required

Must echo BidRequest.id.

cur

string

required

Must be "USD".

seatbid

array

required

Multiple seatbid entries and multiple bid[] per seatbid are accepted. The SSP picks the highest-priced bid across all seatbids as your DSP’s representative for the cross-DSP auction. Ties are broken by first encountered. Bids with bid.cur set to anything other than "USD" are dropped before pricing. Non-winning bids in the same response still get an lurl notification — see Notifications below.

`seatbid[]`

seat

string

Buyer seat id. Identifies which buyer at your DSP placed the bid (e.g. agency, advertiser, or trading desk). Surfaced in Thrad analytics for per-seat revenue and quality slicing — recommended whenever your DSP fronts multiple buyers. Optional; omit or send empty if you have no seat concept.

`seatbid[].bid[]`

string

required

Your unique bid id. Correlated with nurl, lurl, burl.

impid

string

required

Must echo "1" (Thrad sends a single impression per request). Non-"1" values are accepted today but logged for follow-up; strict envelope validation (v2) will hard-reject.

price

float

required

CPM USD. Must be ≥ imp.bidfloor. 2 decimal places — bids with more precision are rounded using ROUND_HALF_UP (see Pricing & Commission).

adm

string

required

JSON-encoded Native 1.2 ad markup. Both wrapper styles are accepted — the SSP auto-detects which one your DSP emits:Spec-correct Native 1.2 (unwrapped, recommended):

{
  "ver": "1.2",
  "assets": [
    { "id": 1, "title": { "text": "Best CRM for startups" } },
    { "id": 2, "data": { "value": "Try HubSpot free for 30 days." } },
    { "id": 3, "data": { "value": "HubSpot" } },
    { "id": 4, "img": { "url": "https://your-dsp.com/img/hero.jpg", "w": 1200, "h": 627 } },
    { "id": 5, "img": { "url": "https://your-dsp.com/img/logo.png", "w": 100, "h": 100 } },
    { "id": 6, "data": { "value": "Try Free" } }
  ],
  "link": { "url": "https://your-dsp.com/click/abc123?price=${AUCTION_PRICE}" },
  "eventtrackers": [
    { "event": 1, "method": 1, "url": "https://your-dsp.com/imp/abc123" }
  ]
}

Legacy Native 1.0/1.1 (wrapped, also accepted):

{ "native": { "ver": "1.2", "assets": [ ... ], "link": { ... }, "eventtrackers": [ ... ] } }

Native 1.2 §5.1 deprecated the outer native wrapper, but a meaningful share of DSPs still emit it. The SSP peels the wrapper when present and processes either shape identically. If adm.ver is set to anything other than "1.2", a warning is logged and the bid still flows.Impression trackers. The SSP prefers Native 1.2 eventtrackers[event=1, method=1]. When eventtrackers is missing or empty, it falls back to the legacy native.imptrackers[] array (Native 1.0/1.1 compat) — bare URL strings, treated as event=1 + method=1.Asset ids must match those requested. Missing required assets (1, 2, 3, 6) reject the bid.

Asset id	Publisher field
1 (title)	`headline`
2 (data.desc)	`description`
3 (data.sponsoredBy)	`advertiser`
4 (img.main)	`image_url`
5 (img.icon)	`logo_url`
6 (data.ctatext)	`cta_text`
`link.url`	`url` (wrapped through Thrad click redirect)
`eventtrackers[event=1].url`	`view_url`

adomain

string[]

required

Advertiser domain(s). Used for brand-safety. Required and must be non-empty — bids with empty adomain log a warning today and are hard-rejected under strict envelope validation (v2).

nurl

string

Win notification URL. Fired once on win, before delivery. Include ${AUCTION_PRICE}. Must be HTTPS — non-HTTPS URLs are dropped server-side (the bid still wins, only the notification is skipped).

lurl

string

Loss notification URL. Fired once on loss. Include ${AUCTION_LOSS}. Must be HTTPS — non-HTTPS URLs are dropped.

burl

string

Billing URL. Fired once after publisher confirms impression rendered. Use for spend recognition. Must be HTTPS — non-HTTPS URLs are dropped.

cid

string

Campaign id. Recorded on the impression for analytics.

crid

string

Creative id. Recorded on the impression for analytics.

cat

string[]

IAB category for the creative. First entry is recorded on the impression for analytics.

Server validation

Limits and checks the SSP applies to your response. Today most are log-only (the bid still flows) so DSPs get visibility before strict mode lands; strict envelope validation (v2) flips the listed checks to hard rejects.

Check	Behaviour today	Notes
Response body size	Hard cap 1 MB (rejected before JSON parse)	Real oRTB responses are 1–10 KB; the cap is generous
`seatbid[]` count	Hard cap 10 — extras are truncated with a log	Real responses send 1–3
`bid[]` per seatbid	Hard cap 20 — extras are truncated with a log	Real responses send 1–5
`BidResponse.id` echoes `BidRequest.id`	Log-only	Will hard-reject under strict mode
`cur == "USD"` (envelope)	Log-only	Per-bid `bid.cur != "USD"` is dropped today
`bid.impid == "1"`	Log-only	Will hard-reject under strict mode
`bid.adomain` non-empty	Log-only	Will hard-reject under strict mode
`adm.ver == "1.2"`	Log-only	Other versions accepted but flagged
`nurl` / `lurl` / `burl` are HTTPS	URL dropped, bid still wins	Non-HTTPS leaks auction data in cleartext
Asset shape matches request (id → outer/inner)	Log-only	Surfaces drift before it degrades to `ortb_no_renderable_asset`
Image asset dimensions ≥ requested `wmin` / `hmin`	Log-only	Declared dims only — fetched audit lands later
Text asset length ≤ requested `len`	Log-only	Title limit is per-publisher (`max_headline_chars`)

Notifications

All three are fire-and-forget GETs (~2 s timeout, no retry). Errors are logged and swallowed — no part of the auction or render path waits on them.

URL	When fired	Use for
`nurl`	Auction win, after creative is committed for render	Bid bookkeeping, pacing
`lurl`	Auction loss (cross-DSP and in-response)	Bidder tuning, price learning
`burl`	Publisher impression confirmation	Spend recognition, billing

Loss notifications (`lurl`) for multi-bid responses

The SSP fires lurl in two situations and your endpoint should be able to handle both:

Cross-DSP loser — your DSP’s representative bid (highest-priced bid in your response) lost the cross-DSP auction to another DSP. Reason code 102 (“lost to higher bid”).
In-response loser — a non-winning bid inside your own response (you sent multiple bids in one or more seatbids; only the highest-priced one became your representative). Each in-response loser gets its own lurl fired with reason code 102. This happens regardless of whether your representative bid won the cross-DSP auction — i.e. even if your DSP is the overall winner, your other bids in the same response still receive a loss notice.

Bids dropped before pricing (non-USD bid.cur, missing price) do not receive an lurl.Loss reason codes (${AUCTION_LOSS}):

Code	Meaning	Status
102	Lost to higher bid (cross-DSP or in-response)	Fired today
100	Bid below floor	Coming soon
3	Invalid bid response	Coming soon
7	Invalid `adm`	Coming soon
6	Advertiser domain blocked	Reserved (not yet wired)
1	Internal SSP error	Reserved (not yet wired)

Today the SSP only fires lurl with reason 102. Other rejection cases (below-floor, invalid response, invalid adm) drop the bid silently. Wiring those rejections to fire lurl with the appropriate code is on the v2 roadmap — your endpoint should be ready to receive them, but should also handle long stretches with only 102 in the wild.

Price macros — substituted in nurl, lurl, burl, adm, and adm.link.url:

Macro	Value
`${AUCTION_PRICE}`	Clearing price (CPM USD, 2 decimals)
`${AUCTION_ID}`	`BidRequest.id`
`${AUCTION_BID_ID}`	`bid.id`
`${AUCTION_IMP_ID}`	Always `"1"`
`${AUCTION_CURRENCY}`	`"USD"`
`${AUCTION_LOSS}`	Loss reason code

No-bid

Option	When to use
`204 No Content`	Default. Lowest overhead.
`200` + `nbr`	When reason code helps your analytics.
`200` + empty `seatbid: []`	Legacy fallback.

Common nbr codes: 7 blocked publisher, 8 unmatched user, 9 reader cap, 10 DSP bid cap.

{
  "id": "auction_987654321",
  "cur": "USD",
  "seatbid": [{
    "seat": "your-dsp",
    "bid": [{
      "id": "bid_abc123",
      "impid": "1",
      "price": 7.50,
      "adm": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"title\":{\"text\":\"Best CRM for startups\"}},{\"id\":2,\"data\":{\"value\":\"Try HubSpot free for 30 days.\"}},{\"id\":3,\"data\":{\"value\":\"HubSpot\"}},{\"id\":4,\"img\":{\"url\":\"https://your-dsp.com/img/hero.jpg\",\"w\":1200,\"h\":627}},{\"id\":5,\"img\":{\"url\":\"https://your-dsp.com/img/logo.png\",\"w\":100,\"h\":100}},{\"id\":6,\"data\":{\"value\":\"Try Free\"}}],\"link\":{\"url\":\"https://your-dsp.com/click/abc123?price=${AUCTION_PRICE}\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://your-dsp.com/imp/abc123\"}]}}",
      "adomain": ["hubspot.com"],
      "crid": "creative_42",
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "lurl": "https://your-dsp.com/loss?bid=${AUCTION_BID_ID}&reason=${AUCTION_LOSS}",
      "burl": "https://your-dsp.com/billed?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}"
    }]
  }]
}

Onboarding

​Authentication

​Envelope

​imp[]

​site / app

​app block (in-app inventory only)

​device

​user

​regs

​source

​bcat / badv

​Envelope

​seatbid[]

​seatbid[].bid[]

​Server validation

​Notifications

​Loss notifications (lurl) for multi-bid responses

​No-bid

Authentication

Envelope

`imp[]`

`site` / `app`

`app` block (in-app inventory only)

`device`

`user`

`regs`

`source`

`bcat` / `badv`

Envelope

`seatbid[]`

`seatbid[].bid[]`

Server validation

Notifications

Loss notifications (`lurl`) for multi-bid responses

No-bid