> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List demand signals

> List buyer demand routed to a storefront you own

`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

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.interchange.io/api/v2/storefront/storefronts/4471/demand-signals?status=SEARCHING&minMatchPct=60&limit=25" \
    -H "Authorization: Bearer $SCOPE3_API_KEY"
  ```

  ```bash Filter by channel and dispatch state theme={null}
  curl "https://api.interchange.io/api/v2/storefront/storefronts/4471/demand-signals?channel=ctv&dispatchStatus=ACKNOWLEDGED" \
    -H "Authorization: Bearer $SCOPE3_API_KEY"
  ```
</CodeGroup>

## 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

```json theme={null}
{
  "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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Demand signal tasks" href="/v2/storefront/demand-signals/tasks" icon="list-check">
    All demand-signal operations
  </Card>

  <Card title="Get demand signal" href="/v2/storefront/demand-signals/tasks/get-demand-signal" icon="magnifying-glass">
    One signal with its target row
  </Card>

  <Card title="Test-fit demand signal" href="/v2/storefront/demand-signals/tasks/test-fit-demand-signal" icon="flask">
    Preview the match before responding
  </Card>

  <Card title="Respond to demand signal" href="/v2/storefront/demand-signals/tasks/respond-to-demand-signal" icon="reply">
    QUOTE, CLARIFY, DECLINE, or BOOK
  </Card>
</CardGroup>