# 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:

```http
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:

```http
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:

```http
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:

```http
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](https://api.trillboards.com/docs/guides/integrations/demand-buyer).
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:

```http
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: vistar` remains a compatibility alias for `partner`.
  Existing IDs and other documented wire enums containing `vistar` remain opaque
  compatibility values.
- Existing device/delta cursors, `since` and `format=openrtb` remain 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 for
  `amountMinor`/`reviewedAmount`. Prices, quantities and accepted IDs survive
  retries. Fresh and historical replays omit supplier payout fields
  `revenue_split`, `has_distributor` and `distributor_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 `days` from 1 to 90,
  selecting that many periods of 24 completed UTC hours ending at `coverage.as_of`.
  `coverage.window_basis` is `completed_utc_hours`; missing hours or a stale recent-hour
  refresh return 503. `coverage.oldest_snapshot_at` names 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](https://api.trillboards.com/docs/guides/integrations/demand-dsp),
[supplier journey](https://api.trillboards.com/docs/guides/integrations/demand-supplier),
[Data, market and supply-chain journey](https://api.trillboards.com/docs/guides/integrations/demand-data-market-supply-chain)
and [metric dictionary](https://api.trillboards.com/docs/guides/reference/demand-metrics).

## 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.
