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

​
Parameters

FieldTypeRequiredNotes
storefrontIdintegerYesStorefront the caller owns (path)
statusenumNoSEARCHING, QUOTED, BOOKED, ABANDONED, DECLINED
dispatchStatusenumNoPer-target state: QUEUED, DISPATCHED, ACKNOWLEDGED, ON_HOLD, FAILED, DECLINED
channelenumNodisplay, native, video, audio, ctv, dooh, newsletter, podcast
minMatchPctintegerNoMinimum match score, 0–100
limitintegerNoPage size, max 100
offsetintegerNoResult 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