Create feed-backed modular source

POST /api/v2/storefront/inventory-sources/modular/feed Creates a real MODULAR_SOURCE for sellers who manage availability through a spreadsheet, export, or manual feed rather than a live ad-server integration. The source is created with the built-in avails-feed module and, by default, the built-in booking ledger. This endpoint does not attach arbitrary execution, reporting, creative, or OMS adapters. Those details can be stored as non-secret setup metadata until a matching module exists.

Request

curl -X POST https://api.interchange.io/api/v2/storefront/inventory-sources/modular/feed \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "reachafrica-ctv",
    "name": "ReachAfrica CTV Avails",
    "availsSource": {
      "type": "spreadsheet",
      "cadence": "monthly",
      "description": "Seller uploads monthly South Africa CTV avails"
    },
    "booking": {
      "mode": "booking_ledger"
    },
    "execution": {
      "mode": "manual",
      "systemName": "Seller ops"
    },
    "reporting": {
      "mode": "upload",
      "sampleAvailable": true
    },
    "creative": {
      "mode": "manual",
      "notes": "Human review confirms broadcast specs"
    }
  }'

Parameters

Field	Type	Required	Notes
`name`	string	Yes	Seller-facing source name, 1-255 characters
`sourceId`	string	No	Storefront-scoped ID. Lowercase letters, numbers, dashes, or underscores only. Defaults to a slugified `name`
`includeBookingLedger`	boolean	No	Defaults to `true`. Set `false` only when Interchange should not hold capacity against this feed
`availsSource.type`	enum	No	`upload`, `spreadsheet`, `api`, `manual`, or `unknown`
`availsSource.cadence`	string	No	Human-readable update cadence, such as `monthly`
`availsSource.description`	string	No	Non-secret feed description
`booking.mode`	enum	No	`booking_ledger`, `manual`, or `upstream_oms`
`booking.systemName`	string	No	Non-secret OMS or booking system name
`booking.notes`	string	No	Non-secret booking notes
`execution.mode`	enum	No	`manual`, `upstream_system`, or `none`
`execution.systemName`	string	No	Non-secret execution system name
`reporting.mode`	enum	No	`upload`, `manual`, `upstream_export`, `api`, or `none`
`reporting.systemName`	string	No	Non-secret reporting system name
`reporting.sampleAvailable`	boolean	No	Whether the seller has provided or can provide a sample report export
`creative.mode`	enum	No	`manual`, `upstream_system`, or `none`
`creative.systemName`	string	No	Non-secret creative workflow system name
`notes`	string	No	Non-secret setup notes

Do not send secrets in this request. API keys, login credentials, private keys, and service-account files must use the appropriate credential flow for the module or ad-server connection.

Response

201 Created with the new source id and modular runtime projection:

{
  "inventorySourceId": "900222",
  "sourceId": "reachafrica-ctv",
  "projection": {
    "inventorySource": {
      "id": "900222",
      "sourceId": "reachafrica-ctv",
      "name": "ReachAfrica CTV Avails",
      "executionType": "MODULAR_SOURCE",
      "status": "ACTIVE",
      "healthStatus": "healthy"
    },
    "modules": [
      {
        "moduleInstanceId": "static-avails-feed",
        "kind": "INVENTORY_FEED",
        "provider": "agentic",
        "status": "ACTIVE"
      },
      {
        "moduleInstanceId": "booking-ledger",
        "kind": "BOOKING_LEDGER",
        "provider": "agentic",
        "status": "ACTIVE"
      }
    ],
    "activeAvailCount": 0,
    "openWorkItemCount": 0
  }
}

After creating the source, upload or paste avails into POST /api/v2/storefront/inventory-sources/{sourceId}/modular/avails-feed. Preview normalized rows first, then commit only after confirming row grain and net sellable capacity.

Errors

400 VALIDATION_ERROR — missing name or invalid sourceId.
401 UNAUTHORIZED — missing or invalid API key.
404 NOT_FOUND — the caller does not have a storefront.
409 CONFLICT — another active source already uses the same sourceId.

See Errors for the full error contract.

Modular lifecycle

How feed, booking, HITL, and reporting stages fit together

Get modular readiness

Inspect modules and lifecycle status

Update module config

Update non-secret module setup

Inventory source tasks

All operations

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Create feed-backed modular source

Request

Parameters

Response

Errors

Modular lifecycle

Get modular readiness

Update module config

Inventory source tasks

​Request

​Parameters

​Response

​Errors

​Related

Modular lifecycle

Get modular readiness

Update module config

Inventory source tasks

Request

Parameters

Response

Errors

Related