# Use the Ads portal API through Demand

The Demand/DSP reference documents the existing HTTP endpoints used by the Trillboards Ads portal. Use the same advertiser JWT, inventory filters, campaign identifiers and checkout flow.

Open the [Demand reference](https://api.trillboards.com/docs#demand) or download the [DSP OpenAPI document](https://api.trillboards.com/openrtb/v2/openapi.json). Start with the Ads inventory, planning, campaigns, creatives, billing, reporting and account sections.

## Use the advertiser portal JWT

Sign in with the existing advertiser account through `POST /v1/user/login`, using `email`, `password` and `user_role: "ADVERTISER"`. The response's top-level `token` is the advertiser JWT. Send it unchanged as `Authorization: Bearer <token>`.

```bash
export ADS_API='https://api.trillboards.com'
export TRILLBOARDS_ADVERTISER_JWT='YOUR_ADVERTISER_PORTAL_JWT'

curl --fail-with-body -sS "$ADS_API/v1/advertiser/advertisement-list" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_JWT"
```

Each operation declares its existing credentials. Media-plan operations also accept an advertiser-scoped platform key where listed. The native portal endpoints use the same account and authorization as the portal.

## Search with the complete inventory filter

`POST /v1/advertiser/inventory/search` accepts the portal's shared inventory filter. It includes radius, bounding box, polygon, postal and market selection; screen and publisher inclusion/exclusion; venue, environment and placement; availability, audience, pricing, time windows and sorting. Use the operation's schema for the complete field and enum definitions.

Save a filter such as this to `inventory-filter.json`:

```json
{
  "source": "all",
  "inventory_class": "owned_and_operated",
  "radius": {
    "center": {
      "lat": 40.7,
      "lng": -74
    },
    "miles": 25
  },
  "venue_category": [
    "retail"
  ],
  "environment_type": [
    "indoor"
  ],
  "placement_type": [
    "wall"
  ],
  "online_status": "recent",
  "min_impressions": 0,
  "price_min": 1,
  "price_max": 40,
  "audience": {
    "age_range": [
      25,
      54
    ],
    "income_range": [
      50000,
      200000
    ],
    "hard": true,
    "min_fit": 0.3
  },
  "time_windows": [
    {
      "start_time": "08:00",
      "end_time": "10:00"
    },
    {
      "start_time": "17:00",
      "end_time": "20:00"
    }
  ],
  "sort": "audience",
  "limit": 100
}
```

```bash
curl --fail-with-body -sS "$ADS_API/v1/advertiser/inventory/search" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_JWT" \
  -H 'Content-Type: application/json' \
  -d @inventory-filter.json
```

`source: "all"` searches the available catalogues. `inventory_class` independently selects the connection class. `owned_and_operated` includes independently owned screens with an established direct Trillboards player, screen API or ad-server connection. Use `partner` for inventory outside that connection.

## Filter screen capabilities

The portal uses `GET /v1/advertiser/screen-list` for screen size, orientation, audio, duration, approval and content controls. These are query parameters:

```bash
curl --fail-with-body -sS \
  "$ADS_API/v1/advertiser/screen-list?latitude=40.7&longitude=-74&radius=25&source=all&audio_enabled=true&min_screen_size=32&max_screen_size=85&screen_orientation=landscape&max_video_duration=30&auto_approval=true&page=1&limit=100" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_JWT"
```

The same route exposes `device_platforms`, `content_allowed`, venue/environment/placement selections, publisher inclusion/exclusion and price-range controls. Keep the native parameter names, including `max_video_duration`.

## Continue the native campaign workflow

| Action | Existing endpoint |
| --- | --- |
| List campaigns | `GET /v1/advertiser/advertisement-list` |
| Read a campaign | `GET /v1/advertiser/advertisement-detail?id=<id>` |
| Create a campaign | `POST /v1/advertiser/create-advertisement` |
| Update a campaign | `PUT /v1/advertiser/update-advertisement/{id}` |
| Replace creative | `POST /v1/advertiser/advertisements/{id}/creative-replacements` |
| Quote selected inventory | `POST /v1/advertiser/impression-quote` |
| Book the selection | `POST /v1/advertiser/impression-book` |
| Create native checkout | `POST /v1/user/marketplace-checkout-session` |
| Read checkout receipt | `GET /v1/user/marketplace-checkout-session/{sessionId}` |
| Generate a report | `POST /v1/advertiser/reports/generate` |

Create and update use the native multipart form. Creative replacement accepts a single `creative` file or the documented `creatives` image-set fields. Use each operation's request schema for its exact required fields and response media, including streamed reports.

Keep the returned campaign, screen, booking and provider-line identifiers unchanged. Pass the exact quote and selection reviewed with the buyer to native checkout, complete payment at its returned URL, and read the native receipt and campaign status.

## Use the SDK and CLI

The official client uses the same native operation IDs and request shapes as the reference. Give it the portal JWT directly.

```js
import {readFile} from 'node:fs/promises';
import {AdvertiserClient} from '@trillboards/api-client';

const ads = new AdvertiserClient({
  token: process.env.TRILLBOARDS_ADVERTISER_JWT,
});
const filter = JSON.parse(await readFile('inventory-filter.json', 'utf8'));
const inventory = await ads.request('adspostV1AdvertiserInventorySearch', {
  body: filter,
});
const campaigns = await ads.request('adsgetV1AdvertiserAdvertisementList', {
  query: {page: 1, limit: 20},
});

// Native multipart upload: the same fields the portal submits.
const campaign = await ads.request('adspostV1AdvertiserCreateAdvertisement', {
  body: {
    name: 'Campaign draft',
    description: 'Campaign creative',
    campaign_link: 'https://example.com',
    photos: [new Blob([await readFile('creative.png')], {type: 'image/png'})],
  },
});
```

Use `params` for SDK path parameters and `headers` for native action headers such as `If-Match`. JSON responses retain their native shape, CSV/text returns a string, and PDF/image responses return a `Blob`. The [maintained Node example](https://api.trillboards.com/docs/guides/examples/demand-buyer-js) also accepts a native operation ID and a JSON file containing `body`, `query`, `params` or `headers`.

The existing CLI API command uses the same user session:

```bash
export TRILLBOARDS_USER_TOKEN="$TRILLBOARDS_ADVERTISER_JWT"
trillboards api GET /v1/advertiser/advertisement-list --user
trillboards api POST /v1/advertiser/create-advertisement --user \
  --data '{"name":"Campaign draft","description":"Campaign creative","campaign_link":"https://example.com"}' \
  --file 'photos=creative.png;type=image/png'
```

Repeat `--query` for repeated query values, `--file` for multiple uploaded files and `--header` for declared action headers. `--output report.pdf` saves a binary report. Public login/account operations use `--anonymous`; protected native operations use `--user`.

## Use the same operations through MCP

Connect to `https://api.trillboards.com/mcp/advertiser` with the same `Authorization: Bearer <portal JWT>` header. JWT connections expose two tools:

- `discover_ads_operations` lists native operations or returns one operation's complete request and response contract.
- `execute_ads_operation` invokes that existing native operation using its original credentials, fields, status codes and responses.

For example, discover `adspostV1AdvertiserInventorySearch`, then call:

```json
{
  "operationId": "adspostV1AdvertiserInventorySearch",
  "body": {
    "source": "all",
    "inventory_class": "all",
    "radius": {"center": {"lat": 40.7, "lng": -74}, "miles": 25},
    "limit": 100
  }
}
```

MCP uses `path` for path values, `query` for query values, `body` for the native body and `headers` for declared action headers. Multipart files use `files` entries with `field`, `filename`, optional `mime_type`, and either `data_base64` or `download_url`. Use the native `photos` field for initial campaign images and `creative`/`creatives` for replacements.

These tools cover proposals, campaign management, uploads, billing and reporting through the native routes. Existing OAuth connections retain the twelve delegated buying tools described below.

## Proposals, payment and readback

Use `/v1/advertiser/proposals` and its documented editor, version, preview and publication operations for actual advertiser proposals. Where a response returns a revision/ETag, pass the documented strong `If-Match` header on its corresponding update. Proposal block and route-week reads include `data.revision`; use its quoted string as `If-Match` when saving with the SDK.

For hosted payment, create the native checkout session, complete payment at the returned Stripe URL and read `GET /v1/user/marketplace-checkout-session/{sessionId}?advertisement_id=<id>` with the same JWT. The return URL is navigation; the native receipt and payment capture determine whether payment completed.

Applications embedding the portal's existing card flow can use `POST /v1/user/marketplace-payment-intent` and `GET /v1/user/payment-methods`. Confirm the returned `client_secret` with Stripe.js and the selected payment method, as the portal does; see [Stripe's card confirmation reference](https://docs.stripe.com/js/payment_intents/confirm_card_payment). Read native campaign status and `GET /v1/advertiser/payment-list` afterward; a payment-history row's `payment_id` identifies its PaymentIntent.

Read per-line booking and fulfillment state before treating an order as live. Quotes, creative review, charging, payment activation and delivery keep their existing native owners.

## Optional delegated buyer workflow

The following workflow is for integrations using advertiser OAuth and the twelve `/openrtb/v2/buying` operations. The native JWT routes above remain the portal workflow.


Use advertiser buying for a planned campaign across screens and available streaming or digital products. REST, the advertiser MCP profile and the advertiser portal use the same campaign, creative review, booking, payment and reporting records.

The [Demand reference](https://api.trillboards.com/docs#demand) contains the complete contract. The [DSP and buyer OpenAPI](https://api.trillboards.com/openrtb/v2/openapi.json) contains the buyer operations. The [maintained JavaScript example](https://api.trillboards.com/docs/guides/examples/demand-buyer-js) supports the native operation IDs above and the delegated actions below.

### Connect the advertiser account

Read [the protected-resource metadata](https://api.trillboards.com/.well-known/oauth-protected-resource/openrtb/v2/buying), follow its authorization server and use Authorization Code with PKCE S256. Send this exact resource on authorization and token requests:

```text
https://api.trillboards.com/openrtb/v2/buying
```

Request `campaigns:read campaigns:write checkout:write` for the complete journey. Use the returned access token as `Authorization: Bearer …`. A DSP or Partner API key does not identify the paying advertiser. The advertiser MCP profile has its own resource, `https://api.trillboards.com/mcp/advertiser`; tokens for one resource are refused by the other.

Inventory search and an unsaved plan preview accept an absent credential. A credential supplied to either must still be valid for the buying resource. Preparing an existing campaign requires `campaigns:read`; checkout requires `checkout:write`.

### Choose inventory and preview

`source` selects a catalogue: `owned`, `partner` or `mixed`. `inventoryClass` selects the connection class: `all`, `owned_and_operated` or `partner`. These are independent filters.

An established direct player, API or validated adserver connection makes a screen `owned_and_operated`, including screens owned by another organization. Registration alone, including creating a tag, does not establish that connection. Ordinary outages affect current readiness without changing the established class. Follow the returned availability, creative and fulfillment state when deciding what can run.

Keep returned screen, product and line identifiers unchanged. Catalogue origin and connection class are independent.

```bash
export TRILLBOARDS_ADVERTISER_ACCESS_TOKEN='YOUR_ADVERTISER_OAUTH_ACCESS_TOKEN'
export ADVERTISER_BUYING_RESOURCE='https://api.trillboards.com/openrtb/v2/buying'
export BUYING_API='https://api.trillboards.com/openrtb/v2/buying'

curl --fail-with-body -sS "$BUYING_API/inventory/search" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"mixed","inventoryClass":"all","limit":20}'
```

For a neighborhood, use `radius:{lat,lng,miles}`. A text or city match is not a neighborhood boundary. Continue with the exact returned `nextCursor` and unchanged search context; start a new search after changing its filters or account.

Write the desired flight, selections and budget to `plan.json`. Use calendar dates and an IANA timezone for local screen schedules. For a mixed screen selection, set the allocation for each source with `ownedBudgetUsd`/`partnerBudgetUsd` or the corresponding impression fields. Provider products use `providerPlan` with `channels`, `selectedProductIds`, `budgetUsd`, `flightStart` and `flightEnd`.

```bash
curl --fail-with-body -sS "$BUYING_API/plans/preview" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' -d @plan.json
```

Preview returns screen forecasts or quotes in `screenQuotes` and, when requested, a provider-product `quote`. A forecast or accepted bid does not reserve inventory.

### Save, attach artwork and review

Give each new write action a stable caller key. Set `TRILLBOARDS_BUYER_ACTION_ID` once for this intended action; keep it and the exact input unchanged when retrying. Use a new action ID when the intended change changes.

```bash
export TRILLBOARDS_BUYER_ACTION_ID='YOUR_UNIQUE_ACTION_ID'

curl --fail-with-body -sS "$BUYING_API/campaigns" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_ACCESS_TOKEN" \
  -H "Idempotency-Key: $TRILLBOARDS_BUYER_ACTION_ID:save" \
  -H 'Content-Type: application/json' -d @plan.json > saved.json
export CAMPAIGN_ID="$(jq -r '.advertisementId' saved.json)"
```

The response preserves the brief even while artwork is pending. It returns native `bookingIds` and `providerLineIds` for accepted selections. Upload artwork through the campaign's existing asset and review flow:

```bash
curl --fail-with-body -sS "$BUYING_API/campaigns/$CAMPAIGN_ID/creative" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_ACCESS_TOKEN" \
  -H "Idempotency-Key: $TRILLBOARDS_BUYER_ACTION_ID:attach" \
  -H 'Content-Type: application/json' -d @creative.json
```

`creative.json` contains `{"creativeFile":{"download_url":"https://YOUR_MEDIA_HOST/creative.mp4","file_id":"YOUR_SELECTED_FILE_ID","mime_type":"video/mp4","file_name":"creative.mp4"}}`. The API copies the selected file into the native asset store. An initial import can return 200; a staged replacement can return 202. Read campaign status for the actual review outcome. An accepted upload does not imply approval.

After approval, save the plan again with the returned `advertisementId` and a new save action key to obtain current accepted screen bookings. Reuse current returned selection IDs; paid rows are not replaced by a new unpaid brief.

### Prepare the exact total, then open checkout

Put the current `bookingIds` and `providerLineIds` in `selection.json`. Preparing reads current selections, readiness, taxes and currency without creating a payment session:

```bash
curl --fail-with-body -sS "$BUYING_API/campaigns/$CAMPAIGN_ID/prepare" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' -d @selection.json > prepared.json

jq '{bookingIds,providerLineIds,reviewedSubtotalUsd,reviewedAmount:.amountMinor,
  reviewedCurrency:.currency,reviewedSelection}' prepared.json > checkout.json

curl --fail-with-body -sS "$BUYING_API/campaigns/$CAMPAIGN_ID/checkout" \
  -H "Authorization: Bearer $TRILLBOARDS_ADVERTISER_ACCESS_TOKEN" \
  -H "Idempotency-Key: $TRILLBOARDS_BUYER_ACTION_ID:checkout" \
  -H 'Content-Type: application/json' -d @checkout.json
```

Show the prepared total and currency to the buyer before checkout. Copy `amountMinor` exactly into `reviewedAmount`; it is the returned currency's minor unit. `reviewedSubtotalUsd` is USD major units. Keep `reviewedSelection` unchanged. A 409 after a selection or price change requires a fresh preparation and buyer review.

Open the returned `checkoutUrl` to complete payment. A created checkout session is unpaid. Booking and fulfillment follow the verified native payment outcome and each selected line's fulfillment route. Read status for progress; preserve partial outcomes and owner-confirmation states.

### Read delivery and manage the original campaign

All paths below are relative to `$BUYING_API`. The [JavaScript example](https://api.trillboards.com/docs/guides/examples/demand-buyer-js) implements every call.

| Action | Method and path | Input and scope |
|---|---|---|
| Status | `GET /campaigns/{id}` | `campaigns:read`; read `bookingState`, creative review, line states and `managementCapabilities`. |
| Delivery | `GET /campaigns/{id}/delivery` | `campaigns:read`; optional `startDate`, `endDate`, `period`, `limit`. |
| Rebook | `POST /campaigns/{id}/rebook` | `flightStart`, `flightEnd`; read and write scopes; new unpaid campaign and fresh pricing. |
| Stop | `POST /campaigns/{id}/stop` | Empty body; `campaigns:write`; inspect `partial_stop` and pending owner stops. |
| Amend flight | `POST /campaigns/{id}/flight` | `flightStart`, `flightEnd`; `campaigns:write`; inspect every line result and applied dates. |
| Update metadata | `PATCH /campaigns/{id}` | `campaignName`, `description`, `landingUrl`; `campaigns:write`. |

The seven write actions use separate stable keys: `save`, `attach`, `checkout`, `rebook`, `stop`, `amend` and `metadata`. Same-key retries share the native replay record across REST and advertiser MCP. Changed arguments conflict. Keys expire after 24 hours and remain refused after expiry; read the original campaign status and any returned recovery reference before deciding on a new action.

Flight changes preserve paid quantities and measured progress. A partner owner may need to confirm new dates; requested dates and applied dates have different meanings. Provider products require a fresh plan and rebooking for changed dates. For `partial_stop:true`, read current status and the remaining line outcomes before making another stop attempt with a new action key. Reusing a completed action key returns its recorded result.

Delivery includes canonical `measurement`, pacing, screen performance and source reconciliation. An explicit UTC window wins; otherwise the campaign flight is used, capped at now and the retained 400-day window. Creative detail has its separate 31-day window. Use the [metric dictionary](https://api.trillboards.com/docs/guides/reference/demand-metrics) to interpret units, missing values and reconciliation.

### Run the JavaScript client

Copy the [maintained example](https://api.trillboards.com/docs/guides/examples/demand-buyer-js) to `demand-buyer.mjs`, install the official client and retain the advertiser environment variables above:

```bash
npm install @trillboards/api-client
node demand-buyer.mjs search search.json
node demand-buyer.mjs preview plan.json
node demand-buyer.mjs save plan.json
```

For a path operation, the input JSON includes `advertisementId` plus that operation's fields. `get` and `stop` accept only `advertisementId`; `delivery` accepts the ID plus its query fields. The other commands are `attach`, `prepare`, `checkout`, `rebook`, `amend` and `metadata`. Each performs its real SDK request; review the current campaign and exact prepared total before invoking a write.

MCP discovery uses the standard `tools/list` cursor. Continue with the unchanged `nextCursor` at the same endpoint and protocol until it is absent; the complete buyer catalog can span pages.
