Share a planning brief

POST /api/v2/buyer/planning-briefs Creates a new planning brief (prospective brief) and shares it with one or more publisher targets in a single transaction. Each target identifies either an Interchange storefront (LIVE / COMING_SOON) or an external publisher (NOT_ON_INTERCHANGE). The brief is created in SEARCHING status.

Request

curl

curl -X POST https://api.interchange.io/api/v2/buyer/planning-briefs \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "advertiserId": 12345,
    "buyerName": "Acme Media",
    "advertiserName": "Acme",
    "campaignName": "Q3 CTV Push",
    "audience": "Tech-savvy professionals 25-54",
    "geo": "US, CA",
    "channels": ["ctv", "video"],
    "startDate": "2026-07-01",
    "endDate": "2026-09-30",
    "statedBudget": 250000,
    "currency": "USD",
    "flexibility": { "mode": "flexible", "days": 7 },
    "creativeReady": true,
    "targetingMode": "FILTERED",
    "targets": [
      { "storefrontId": 42, "bucket": "LIVE", "matchPct": 88 },
      { "externalPublisherName": "Pinnacle News", "externalPublisherDomain": "pinnacle.example.com", "bucket": "NOT_ON_INTERCHANGE" }
    ]
  }'

Parameters

Field	Type	Required	Notes
`buyerName`	string	Yes	Buyer display name (1–200)
`advertiserName`	string	Yes	Advertiser display name (1–200)
`audience`	string	Yes	Target audience description (1–1000)
`geo`	string	Yes	Geography description (1–200)
`channels`	array	Yes	One or more of `display`, `native`, `video`, `audio`, `ctv`, `dooh`, `newsletter`, `podcast`
`startDate` / `endDate`	string	Yes	Flight dates
`statedBudget`	number	Yes	Total budget (> 0)
`currency`	string	Yes	3-letter ISO currency code
`advertiserId`	integer	No	Owning advertiser
`campaignName`	string	No	Prospective campaign name (1–200)
`exclusions`	array	No	`{ type, values?, raw? }`; `type` is `category`, `adjacency`, `competitor`, `domain`, `keyword`, or `raw`
`flexibility`	object	No	`{ mode, days? }`; `mode` is `firm`, `flexible`, or `open`
`primaryKpi`	object	No	`{ raw, parsed? }` where `parsed` is `{ kpi, op, value }`
`priceExpect`	number	No	Expected CPM/price (> 0)
`creativeReady`	boolean	No	Whether creative is ready
`rawPrompt`	string	No	Original free-text prompt (max 4000)
`targetingMode`	enum	No	`DIRECT`, `FILTERED`, or `BROAD`
`targets`	array	No	Publisher targets (max 200). Each requires `bucket`; identify by `storefrontId` or `externalPublisherName` + `externalPublisherDomain`
`targets[].bucket`	enum	Yes (per target)	`LIVE`, `COMING_SOON`, or `NOT_ON_INTERCHANGE`

Response

201 Created — returns the created brief plus its per-publisher target rows (DemandSignalWithTargets).

{
  "id": "7391052846",
  "customerId": 100,
  "advertiserId": 12345,
  "buyerName": "Acme Media",
  "advertiserName": "Acme",
  "audience": "Tech-savvy professionals 25-54",
  "geo": "US, CA",
  "channels": ["ctv", "video"],
  "startDate": "2026-07-01",
  "endDate": "2026-09-30",
  "statedBudget": 250000,
  "currency": "USD",
  "status": "SEARCHING",
  "targetingMode": "FILTERED",
  "qualifiedBudget": null,
  "recommendedProducts": [],
  "createdAt": "2026-06-01T10:00:00Z",
  "updatedAt": "2026-06-01T10:00:00Z",
  "targets": [
    {
      "id": "7391052901",
      "demandSignalId": "7391052846",
      "storefrontId": "42",
      "externalPublisherName": null,
      "externalPublisherDomain": null,
      "bucket": "LIVE",
      "dispatchStatus": "QUEUED",
      "matchPct": 88,
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-01T10:00:00Z"
    }
  ]
}

Field	Type	Notes
`id`	string	Brief ID — pass to `GET /planning-briefs/:briefId`
`status`	enum	`SEARCHING` on create
`targets`	array	Per-publisher target rows
`targets[].bucket`	enum	`LIVE`, `COMING_SOON`, `NOT_ON_INTERCHANGE`
`targets[].dispatchStatus`	enum	`QUEUED`, `DISPATCHED`, `ACKNOWLEDGED`, `ON_HOLD`, `FAILED`, `DECLINED`
`targets[].matchPct`	integer \| null	Match percentage, 0–100

Errors

400 VALIDATION_ERROR — missing required field, channels empty, a target missing bucket, or a target supplying both storefrontId and externalPublisherName.
401 UNAUTHORIZED — missing or invalid bearer token.

See Errors for the full error contract.

Planning brief tasks

All planning brief operations

Get planning brief

Brief with target rows

List brief responses

Seller replies

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Request

Parameters

Response

Errors

Planning brief tasks

Get planning brief

List brief responses

​Request

​Parameters

​Response

​Errors

​Related

Planning brief tasks

Get planning brief

List brief responses

Request

Parameters

Response

Errors

Related