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 or download the DSP OpenAPI document. 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>.
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:
{
"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
}
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:
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.
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 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:
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_operationslists native operations or returns one operation's complete request and response contract.execute_ads_operationinvokes that existing native operation using its original credentials, fields, status codes and responses.
For example, discover adspostV1AdvertiserInventorySearch, then call:
{
"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. 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 contains the complete contract. The DSP and buyer OpenAPI contains the buyer operations. The maintained JavaScript example supports the native operation IDs above and the delegated actions below.
Connect the advertiser account
Read the protected-resource metadata, follow its authorization server and use Authorization Code with PKCE S256. Send this exact resource on authorization and token requests:
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.
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.
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.
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:
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:
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 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 to interpret units, missing values and reconciliation.
Run the JavaScript client
Copy the maintained example to demand-buyer.mjs, install the official client and retain the advertiser environment variables above:
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.