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

FieldTypeRequiredNotes
namestringYesSeller-facing source name, 1-255 characters
sourceIdstringNoStorefront-scoped ID. Lowercase letters, numbers, dashes, or underscores only. Defaults to a slugified name
includeBookingLedgerbooleanNoDefaults to true. Set false only when Interchange should not hold capacity against this feed
availsSource.typeenumNoupload, spreadsheet, api, manual, or unknown
availsSource.cadencestringNoHuman-readable update cadence, such as monthly
availsSource.descriptionstringNoNon-secret feed description
booking.modeenumNobooking_ledger, manual, or upstream_oms
booking.systemNamestringNoNon-secret OMS or booking system name
booking.notesstringNoNon-secret booking notes
execution.modeenumNomanual, upstream_system, or none
execution.systemNamestringNoNon-secret execution system name
reporting.modeenumNoupload, manual, upstream_export, api, or none
reporting.systemNamestringNoNon-secret reporting system name
reporting.sampleAvailablebooleanNoWhether the seller has provided or can provide a sample report export
creative.modeenumNomanual, upstream_system, or none
creative.systemNamestringNoNon-secret creative workflow system name
notesstringNoNon-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