Skip to main content
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

FieldTypeRequiredNotes
buyerNamestringYesBuyer display name (1–200)
advertiserNamestringYesAdvertiser display name (1–200)
audiencestringYesTarget audience description (1–1000)
geostringYesGeography description (1–200)
channelsarrayYesOne or more of display, native, video, audio, ctv, dooh, newsletter, podcast
startDate / endDatestringYesFlight dates
statedBudgetnumberYesTotal budget (> 0)
currencystringYes3-letter ISO currency code
advertiserIdintegerNoOwning advertiser
campaignNamestringNoProspective campaign name (1–200)
exclusionsarrayNo{ type, values?, raw? }; type is category, adjacency, competitor, domain, keyword, or raw
flexibilityobjectNo{ mode, days? }; mode is firm, flexible, or open
primaryKpiobjectNo{ raw, parsed? } where parsed is { kpi, op, value }
priceExpectnumberNoExpected CPM/price (> 0)
creativeReadybooleanNoWhether creative is ready
rawPromptstringNoOriginal free-text prompt (max 4000)
targetingModeenumNoDIRECT, FILTERED, or BROAD
targetsarrayNoPublisher targets (max 200). Each requires bucket; identify by storefrontId or externalPublisherName + externalPublisherDomain
targets[].bucketenumYes (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"
    }
  ]
}
FieldTypeNotes
idstringBrief ID — pass to GET /planning-briefs/:briefId
statusenumSEARCHING on create
targetsarrayPer-publisher target rows
targets[].bucketenumLIVE, COMING_SOON, NOT_ON_INTERCHANGE
targets[].dispatchStatusenumQUEUED, DISPATCHED, ACKNOWLEDGED, ON_HOLD, FAILED, DECLINED
targets[].matchPctinteger | nullMatch 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