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

# Get a demand signal routed to a storefront

> Get a single demand signal routed to the caller's storefront, with the per-target row attached. Returns NOT_FOUND if the signal isn't routed to this storefront.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml get /storefronts/{storefrontId}/demand-signals/{signalId}
openapi: 3.0.0
info:
  title: Scope3 Storefront API
  version: 2.0.0
  description: |-
    REST API for partners to manage storefronts, inventory sources, and billing.

    ## Authentication

    All endpoints require a Bearer token in the Authorization header:
    ```
    Authorization: Bearer your-api-key
    ```

    ## Base URL

    `https://api.interchange.io/api/v2/storefront`

    ## For AI Agents

    AI agents can use the MCP endpoint at `/mcp/v2/storefront` with three tools:
    - `initialize`: Start an MCP session
    - `api_call`: Make REST API calls
    - `ask_about_capability`: Learn about API features
servers:
  - url: https://api.interchange.io/api/v2/storefront
    description: Production server
security: []
tags:
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Storefront
    description: Manage storefront and inventory sources
  - name: Storefront Agents
    description: List and manage registered sales, signals, and outcomes agents
  - name: Storefront Activity
    description: Audit log of configuration and inventory changes on the storefront
  - name: Storefront Billing
    description: Payout bank details and billing configuration for storefronts
  - name: AI Usage
    description: Storefront AI token usage visibility by model
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /storefronts/{storefrontId}/demand-signals/{signalId}:
    get:
      tags:
        - Demand Signals
      summary: Get a demand signal routed to a storefront
      description: >-
        Get a single demand signal routed to the caller's storefront, with the
        per-target row attached. Returns NOT_FOUND if the signal isn't routed to
        this storefront.
      operationId: getStorefrontDemandSignal
      parameters:
        - in: path
          name: storefrontId
          schema:
            type: integer
            maximum: 9007199254740991
            minimum: 1
          required: true
        - in: path
          name: signalId
          schema:
            type: integer
            maximum: 9007199254740991
            minimum: 1
          required: true
      responses:
        '200':
          description: Get a demand signal routed to a storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerDemandSignal'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    SellerDemandSignal:
      description: >-
        A demand signal as seen by ONE storefront. Carries only buyer-set brief
        fields + per-storefront state (status, target, storefrontId). Buyer-side
        signal-wide aggregates are intentionally excluded — they have no
        per-storefront variant and would leak competitive activity across
        sellers.
      type: object
      properties:
        id:
          type: string
        customerId:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        advertiserId:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        brandDomain:
          nullable: true
          type: string
        buyerName:
          type: string
        advertiserName:
          type: string
        campaignName:
          nullable: true
          type: string
        audience:
          type: string
        geo:
          type: string
        channels:
          type: array
          items:
            description: >-
              Channel the buyer wants to reach. Maps to ADCP MediaType.
              Lower-case to match the AdCP wire format; only Postgres-enum types
              use UPPERCASE.
            type: string
            enum:
              - display
              - native
              - video
              - audio
              - ctv
              - dooh
              - newsletter
              - podcast
        exclusions:
          type: array
          items:
            $ref: '#/components/schemas/DemandSignalExclusion'
        startDate:
          type: string
        endDate:
          type: string
        flexibility:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DemandSignalFlexibility'
        statedBudget:
          type: number
        currency:
          type: string
        primaryKpi:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DemandSignalKpi'
        priceExpect:
          nullable: true
          type: number
        creativeReady:
          nullable: true
          type: boolean
        rawPrompt:
          nullable: true
          type: string
        targetingMode:
          description: >-
            `DIRECT` = buyer named the seller(s). `FILTERED` = matched ≤5
            candidates. `BROAD` = >5.
          type: string
          enum:
            - DIRECT
            - FILTERED
            - BROAD
        createdAt:
          type: string
        updatedAt:
          type: string
        status:
          description: >-
            Lifecycle of a demand signal. `SEARCHING` on create; `QUOTED` when
            at least one seller responds; `BOOKED` when at least one target
            converts to a deal; `ABANDONED` after idle; `DECLINED` if every
            target declined.
          type: string
          enum:
            - SEARCHING
            - QUOTED
            - BOOKED
            - ABANDONED
            - DECLINED
        storefrontId:
          type: string
        target:
          $ref: '#/components/schemas/DemandSignalTarget'
      required:
        - id
        - customerId
        - advertiserId
        - brandDomain
        - buyerName
        - advertiserName
        - campaignName
        - audience
        - geo
        - channels
        - exclusions
        - startDate
        - endDate
        - flexibility
        - statedBudget
        - currency
        - primaryKpi
        - priceExpect
        - creativeReady
        - rawPrompt
        - targetingMode
        - createdAt
        - updatedAt
        - status
        - storefrontId
        - target
      additionalProperties: false
    ErrorResponse:
      description: Standard error response
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
    DemandSignalExclusion:
      type: object
      properties:
        type:
          type: string
          enum:
            - category
            - adjacency
            - competitor
            - domain
            - keyword
            - raw
        values:
          default: []
          type: array
          items:
            type: string
            minLength: 1
        raw:
          type: string
      required:
        - type
        - values
      additionalProperties: false
    DemandSignalFlexibility:
      type: object
      properties:
        mode:
          type: string
          enum:
            - firm
            - flexible
            - open
        days:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - mode
      additionalProperties: false
    DemandSignalKpi:
      type: object
      properties:
        raw:
          type: string
        parsed:
          type: object
          properties:
            kpi:
              description: Primary KPI buyer is optimizing for (v1 enum).
              type: string
              enum:
                - attention_seconds
                - viewability_pct
                - ctr
                - vcr
                - vtr
                - reach
                - frequency_cap
                - sov
                - brand_lift
                - cpa
            op:
              type: string
              enum:
                - gt
                - gte
                - eq
                - lte
                - lt
            value:
              type: number
          required:
            - kpi
            - op
            - value
          additionalProperties: false
      required:
        - raw
      additionalProperties: false
    DemandSignalTarget:
      description: >-
        One target publisher within a demand signal. Identified by either
        storefrontId (live / coming-soon) or externalPublisherName
        (not-on-Interchange) — never both.
      type: object
      properties:
        id:
          type: string
        demandSignalId:
          type: string
        storefrontId:
          nullable: true
          type: string
        externalPublisherName:
          nullable: true
          type: string
        externalPublisherDomain:
          nullable: true
          type: string
        bucket:
          description: >-
            Where the target publisher sits relative to Interchange. Drives the
            dispatch action (notify / watch / invite).
          type: string
          enum:
            - LIVE
            - COMING_SOON
            - NOT_ON_INTERCHANGE
        dispatchStatus:
          description: >-
            Per-target dispatch state. `ACKNOWLEDGED` means the seller agent
            confirmed receipt; status transitions to `DECLINED` if the agent
            rejects the brief.
          type: string
          enum:
            - QUEUED
            - DISPATCHED
            - ACKNOWLEDGED
            - ON_HOLD
            - FAILED
            - DECLINED
        matchPct:
          nullable: true
          type: integer
          minimum: 0
          maximum: 100
        dispatchAttemptedAt:
          nullable: true
          type: string
        dispatchedAt:
          nullable: true
          type: string
        acknowledgedAt:
          nullable: true
          type: string
        errorMessage:
          nullable: true
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
        - id
        - demandSignalId
        - storefrontId
        - externalPublisherName
        - externalPublisherDomain
        - bucket
        - dispatchStatus
        - matchPct
        - dispatchAttemptedAt
        - dispatchedAt
        - acknowledgedAt
        - errorMessage
        - createdAt
        - updatedAt
      additionalProperties: false
    ApiError:
      description: Structured error object
      type: object
      properties:
        code:
          description: Machine-readable error code
          type: string
        message:
          description: Human-readable error message
          type: string
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````