# Integrate a DSP with the Demand API

Use the DSP interface to discover inventory, obtain issued opportunities, submit OpenRTB responses and read seat-scoped delivery. Use [advertiser buying](https://api.trillboards.com/docs/guides/integrations/demand-buyer) for a planned campaign reviewed and paid by an advertiser. Both connect to the existing serving and reporting system.

## Link a seat to the platform key

Mint the platform key from the existing account or follow the [OpenRTB quickstart](https://api.trillboards.com/docs/guides/quickstart/openrtb). Link that same credential to a DSP seat:

```bash
curl --fail-with-body -sS https://api.trillboards.com/openrtb/v2/onboard \
  -H "Authorization: Bearer $TRILLBOARDS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"company_name":"Your Company","seat_id":"your_company","contact_email":"developer@your-company.example"}'
```

When a platform key is reused, the response records that linkage without returning the secret. New seats start in sandbox. Sandbox validates integration inputs without admitting bids to live selection. Scopes still apply: `inventory:read`, `bid:write`, `stats:read`, `campaigns:write`, `deals:read`, `proof:read` and `reports:read` are route-specific capabilities. Follow the security declaration of the exact operation.

A bilateral exchange uses its provisioned connection at `/openrtb/bidder/{connectionAlias}/bid`. It sends supply-side bid requests through that connection's authentication and callback contract. The DSP control route `POST /openrtb/v2/bid` instead accepts a bid response for an issued opportunity.

## Discover and price candidate inventory

Use `POST /openrtb/v2/discover` for text, geography and catalogue filters. `source` and `inventory_class` are independent: catalogue provenance does not determine delivery connection class.

```bash
curl --fail-with-body -sS https://api.trillboards.com/openrtb/v2/discover \
  -H "Authorization: Bearer $TRILLBOARDS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"coffee","source":"all","inventory_class":"all","limit":20}'
```

An established direct player, API or validated adserver connection is `owned_and_operated`, irrespective of screen ownership. An external publisher can therefore have directly connected inventory. An unconnected catalogue row remains `partner`; registration or tag creation alone does not establish connection. Readiness and availability describe the current opportunity, including outages, separately from class.

Continue with the exact cursor and unchanged query, filters and authenticated seat. Keep returned IDs unchanged, including older opaque IDs and wire enums containing `vistar`. Those identify the existing partner catalogue.

Use `/forecast` and `/screens/availability` for planning, and `/deals` for offers visible to this seat. Discovery, a forecast and an offered deal do not establish a paid placement. Deal proposal creation requires a configured demand-partner linkage; registration alone does not create that commercial relationship.

## Obtain and answer an issued opportunity

```bash
curl --fail-with-body -sS \
  'https://api.trillboards.com/openrtb/v2/adslots?format=openrtb&country=US&limit=20' \
  -H "Authorization: Bearer $TRILLBOARDS_API_KEY"
```

Read the returned `bid_requests`. Use the exact request `id`, impression `id`, currency, floor and current opportunity terms in the response. The issued opportunity belongs to the authenticated seat and has a bounded lifetime. A planning-only partner row is not an issued render opportunity.

Put the actual OpenRTB response and a supported creative in `bid-response.json`:

```bash
curl -sS -D bid-response.headers \
  https://api.trillboards.com/openrtb/v2/bid \
  -H "Authorization: Bearer $TRILLBOARDS_API_KEY" \
  -H 'Content-Type: application/json' -d @bid-response.json
```

In production, HTTP 200 with accepted_count means at least one candidate was admitted; 204 is a normal no-bid result. A sandbox HTTP 200 with status validated and sandbox true confirms validation only and does not admit a live candidate. Admission does not reserve inventory, establish a win, serve an ad or create a billable play. Live selection claims an accepted candidate once through the existing serving path. Win and billing callbacks follow their corresponding selection and completion events.

The seat comes from authentication. A bid's seat, campaign hint or source label cannot select a different account. A campaign hint can target an already authorized native campaign; it does not create a booking or confer ownership.

## Reconcile delivery

Use `GET /openrtb/v2/stats`, the creative and screen reports, and `/analytics/funnel` with `reports:read`. For a funnel, provide `start_date` and `end_date` as UTC dates within the last 90 days. `granularity` accepts `flight`, `daily` or `hourly`; `screen_ids` is an optional comma-separated set.

The funnel describes issued prebid opportunities, accepted responses and their selected starts/completions. Read `coverage` before using its denominator: historical time before issued-opportunity recording is unmeasured. The measured `observed_cohort` is returned separately. It is not a count of all historical VAST requests or all global auctions.

`GET /openrtb/v2/proof-of-play` with `proof:read` reads canonical completed plays. Its `start_date`/`end_date` interval is UTC and end-exclusive, at most 400 days, with the end capped at now. Continue using its returned pagination. Read each record's `verification_tier`; a partner-reported or event-confirmed record is not a signed record.

The retired `GET /openrtb/v1/omsdk/session/{sessionId}` returns 410. Use the documented analytics and verification reports for supported reads.

Continue with [market, Data and supply-chain integration](https://api.trillboards.com/docs/guides/integrations/demand-data-market-supply-chain) and the [metric dictionary](https://api.trillboards.com/docs/guides/reference/demand-metrics).
