Demand API migration — 2026-11-12
This release adds the advertiser buying lifecycle and corrects three legacy behaviors. Keep existing opaque IDs unchanged. DSP credentials, advertiser OAuth and Data entitlements continue to identify their respective resources.
Move catalogue planning out of the prebid feed
Former planning requests such as:
GET /openrtb/v2/adslots?source=vistar
GET /openrtb/v2/adslots?source=all
return HTTP 400 unsupported_source_for_mode, with param: source. The feed accepts an omitted source or source=owned. An omitted inventory_class or inventory_class=all remains valid; other connection-class filters return the same error with param: inventory_class.
Use catalogue discovery instead:
POST /openrtb/v2/discover
Authorization: Bearer <DSP platform key>
Content-Type: application/json
{"source":"all","inventory_class":"all","limit":20}
Advertiser planning uses POST /openrtb/v2/buying/inventory/search with {"source":"mixed","inventoryClass":"all","limit":20}. Catalogue source and connection class are independent. Established direct player, API or validated adserver connections are owned_and_operated, including externally owned screens. Registration or tag creation alone does not establish that class; an ordinary outage changes readiness.
Replace direct assignment with the native buyer workflow
The former purchase call:
POST /openrtb/v2/campaigns/assign
Authorization: Bearer <DSP platform key>
Content-Type: application/json
{"creative_id":"<DSP creative ID>","screen_ids":["<screen ID>"]}
returns HTTP 409 native_buyer_workflow_required. The response provides workflow: /openrtb/v2/buying, the required advertiser OAuth resource and the four operation IDs for draft, artwork, review and checkout. Its legacy body is ignored. createCampaign remains available for DSP auction-targeting metadata and a matching-screen preview; its ready status does not represent a purchase.
Obtain an advertiser OAuth token for https://api.trillboards.com/openrtb/v2/buying, then use:
POST /openrtb/v2/buying/campaigns
POST /openrtb/v2/buying/campaigns/{advertisementId}/creative
POST /openrtb/v2/buying/campaigns/{advertisementId}/prepare
POST /openrtb/v2/buying/campaigns/{advertisementId}/checkout
Use the request bodies in the buyer journey. Each write has its own stable Idempotency-Key. Copy the current prepared reviewedSelection, amountMinor and currency into checkout's reviewed fields. Checkout creation is unpaid; native payment confirmation and creative readiness determine fulfillment. DSP keys and advertiser MCP tokens cannot replace the buying resource's advertiser token.
Answer an issued opportunity with its authenticated seat
A guessed request ID or a screen ID substituted for an impression ID no longer admits a bid. Obtain an issued request first:
GET /openrtb/v2/adslots?format=openrtb&source=owned&limit=1
Authorization: Bearer <DSP platform key>
For POST /openrtb/v2/bid, use a returned bid_requests[].id as the response id, its exact imp[].id as bid.impid, and its currency. Omit seatbid.seat or match the authenticated seat exactly; a different seat returns HTTP 403 unauthorized_seat. Unknown, expired, consumed or currency-mismatched opportunities are refused with unknown_or_expired_opportunity in bid rejection details. A live batch with no accepted candidate returns 204. Sandbox validates the same issued lineage and reports status: validated without live admission.
Acceptance is a candidate. Selection consumes its opportunity once. Admission notifications are bid.accepted and bid.rejected; a win notice follows selection and billing follows the eligible completion. External cid remains external metadata. Optional ext.trillboards.campaign_id must identify a native campaign owned by the advertiser linked to the authenticated DSP.
Retained contracts and reporting corrections
- Buyer catalogue
source: vistarremains a compatibility alias forpartner. Existing IDs and other documented wire enums containingvistarremain opaque compatibility values. - Existing device/delta cursors,
sinceandformat=openrtbremain available on the prebid feed. Buyer discovery cursors require the same account and search context. Start a new search after changing filters. - Buyer monetary units remain explicit: USD major units for quotes and
reviewedSubtotalUsd; the returned currency's minor units foramountMinor/reviewedAmount. Prices, quantities and accepted IDs survive retries. Fresh and historical replays omit supplier payout fieldsrevenue_split,has_distributoranddistributor_code, and the private per-screen floor, surge, audience-quality and ad-performance factors. - Unmeasured report revenue, rates or market premiums are
null; measured zero stays zero. Canonical completed plays, audience plays, placement progress, distinct devices and booked/paid buyer spend retain separate meanings. Unavailable report stores return an error rather than a measured empty result. - Market benchmark and demand-analysis requests accept
daysfrom 1 to 90, selecting that many periods of 24 completed UTC hours ending atcoverage.as_of.coverage.window_basisiscompleted_utc_hours; missing hours or a stale recent-hour refresh return 503.coverage.oldest_snapshot_atnames the oldest hourly refresh start; historical hours refresh daily. Use the returned seven UTC dayparts from the metric dictionary; clients should accept the complete vocabulary. - The retired OMSDK session-status operation continues to return 410.
Continue with the DSP journey, supplier journey, Data, market and supply-chain journey and metric dictionary.
Legacy analytics read corrections
GET /openrtb/v1/analytics/interactions and /analytics/qr-scans now read their existing recorded interaction ledger. Their previous success bodies hardcoded zero counts. Native advertisement ownership or canonical screen access scopes the returned records; telemetry advertiser labels do not grant access. Existing filter names remain. General non-administrator reads use the native advertisement owner. Counts and pagination cover a complete selected window. More than 10,000 matched events returns 413; narrow the window or object filter. Invalid windows return 400, inaccessible object scope returns 404, wholly expired history returns 422, and required read failure returns 503. The response includes the effective UTC window.
GET /openrtb/v1/analytics/impressions keeps its existing canonical row reader and 1,000-row limit. Retired legacy viewability summary values change from zero/string-zero to null; the empty viewabilityMetrics compatibility array remains. Its required ledger failure returns 503.
FEIN creative/venue, fill-rate and model-status reports and the OMSDK campaign verification report return 503 on required source failure. A successful empty read remains an empty cohort. Model gradient counts use the stored uploaded_at; they no longer hide an invalid timestamp query behind zeroes. OMSDK successful reports retain the full report shape, including an empty session cohort. No licensed Data API entitlement or dataset is replaced by these read corrections.