List demand signals - Interchange API

GET /api/v2/storefront/storefronts/{storefrontId}/demand-signals Returns the demand signals routed to the caller’s storefront, each augmented with the per-target row that routed it here and the seller-internal matchPct. Filter by lifecycle status, per-target dispatch state, channel, or minimum match. The caller must own the storefront.

Request

curl "https://api.interchange.io/api/v2/storefront/storefronts/4471/demand-signals?status=SEARCHING&minMatchPct=60&limit=25" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl "https://api.interchange.io/api/v2/storefront/storefronts/4471/demand-signals?channel=ctv&dispatchStatus=ACKNOWLEDGED" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`storefrontId`	integer	Yes	Storefront the caller owns (path)
`status`	enum	No	`SEARCHING`, `QUOTED`, `BOOKED`, `ABANDONED`, `DECLINED`
`dispatchStatus`	enum	No	Per-target state: `QUEUED`, `DISPATCHED`, `ACKNOWLEDGED`, `ON_HOLD`, `FAILED`, `DECLINED`
`channel`	enum	No	`display`, `native`, `video`, `audio`, `ctv`, `dooh`, `newsletter`, `podcast`
`minMatchPct`	integer	No	Minimum match score, 0–100
`limit`	integer	No	Page size, max 100
`offset`	integer	No	Result offset

Response

{
  "items": [
    {
      "id": "ds_8f3a",
      "customerId": 33012,
      "advertiserId": 77140,
      "buyerName": "Northwind Media",
      "advertiserName": "Northwind Outdoors",
      "campaignName": "Spring Gear Launch",
      "audience": "Outdoor enthusiasts, 25-44",
      "geo": "US-CA, US-CO",
      "channels": ["ctv", "video"],
      "exclusions": [{ "type": "category", "values": ["gambling"] }],
      "startDate": "2026-07-01",
      "endDate": "2026-08-31",
      "flexibility": { "mode": "flexible", "days": 14 },
      "statedBudget": 150000,
      "currency": "USD",
      "primaryKpi": { "raw": "VCR above 70%" },
      "priceExpect": 28.0,
      "creativeReady": true,
      "rawPrompt": "Reach outdoor enthusiasts on CTV this summer",
      "targetingMode": "FILTERED",
      "createdAt": "2026-06-05T09:00:00Z",
      "updatedAt": "2026-06-05T09:00:00Z",
      "status": "SEARCHING",
      "storefrontId": "4471",
      "target": {
        "id": "tgt_22a",
        "demandSignalId": "ds_8f3a",
        "storefrontId": "4471",
        "externalPublisherName": null,
        "externalPublisherDomain": null,
        "bucket": "LIVE",
        "dispatchStatus": "ACKNOWLEDGED",
        "matchPct": 72,
        "dispatchAttemptedAt": "2026-06-05T09:01:00Z",
        "dispatchedAt": "2026-06-05T09:01:02Z",
        "acknowledgedAt": "2026-06-05T09:05:00Z",
        "errorMessage": null,
        "createdAt": "2026-06-05T09:00:30Z",
        "updatedAt": "2026-06-05T09:05:00Z"
      }
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextOffset": null
}

matchPct and the target row are seller-internal — buyer-side aggregates are excluded so competitive activity does not leak across sellers. Page with nextOffset when hasMore is true.

Errors

400 VALIDATION_ERROR — invalid status, channel, or out-of-range minMatchPct.
403 FORBIDDEN — the demand-supply-signals feature is not enabled, or the caller does not own the storefront.

See Errors for the full error contract.

Demand signal tasks

All demand-signal operations

Get demand signal

One signal with its target row

Test-fit demand signal

Preview the match before responding

Respond to demand signal

QUOTE, CLARIFY, DECLINE, or BOOK

​Request

​Parameters

​Response

​Errors

​Related