Host your own API: the pull connection

Path C made concrete. If you already run order and inventory systems, you do not rebuild them against Switchboard: you host a small API on your side, and we call it. This page is the contract our adapters build to. Declare what you host in your capability profile and the platform never calls anything else.

What you can host

Direction stays per capability. Host order intake and push avails by file drop, or host everything, or start with intake alone; your profile declares the mix, and you climb levels when you choose to.

The catalog pull

GET/packagesyour host

One endpoint returns everything a plan needs: your packages (recurring inventory: a property, a daypart window, a weekday pattern, a validity window), each package's dated slots, and each slot's rates with availability. These are the same nouns the rest of the marketplace speaks; see Packages.

GET https://api.acmebroadcasting.example/switchboard/packages?start_date=2026-10-05&end_date=2026-10-18

{
  "packages": [{
    "package_id": "ACME-PRIME-MSu",
    "property": "Acme Broadcasting",
    "start_date": "2026-09-28", "end_date": "2026-12-27",
    "daypart_start": "20:00", "daypart_end": "24:00",
    "weekdays": ["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],
    "slots": [{
      "slot_id": "ACME-PRIME-MSu-20261007",
      "date": "2026-10-07",
      "rates": [
        { "class": "standard",    "cost_per_second": 94.0, "hh_impressions": 121000, "available": true },
        { "class": "competitive", "cost_per_second": 86.5, "hh_impressions": 121000, "available": true }
      ]
    }]
  }]
}

• A slot is a dated, orderable instance of a package. A rate is a price and availability entry on a slot.
• We plan against the cached read, then re-check exactly the dates in play just before ordering. Validation remains the backstop for the residual race.

Order intake

POST/ordersyour host

We submit confirmed buyer orders into your system. The submission is the order envelope:

POST https://api.acmebroadcasting.example/switchboard/orders
# body: the order envelope, fields above

202 { "order_id": "ACME-77120", "status": "received", "received_at": "2026-10-05T14:20:00Z" }

GET/orders/{id}your host

The 202 acknowledges receipt under your own order id; the decision comes from the status read, keyed by that id:

GET https://api.acmebroadcasting.example/switchboard/orders/ACME-77120

200 {
  "order_id": "ACME-77120",
  "status": "confirmed",
  "lines": [{
    "slot_id": "ACME-PRIME-MSu-20261007",
    "status": "accepted",
    "num_requested": 4, "num_accepted": 4,
    "allocation": [ { "date": "2026-10-07", "units": 4 } ],
    "reason": null
  }]
}

• Rejected lines carry a reason we can route on, and an all-rejected response is still a successful response; errors are for transport and logic failures only.
• Counters, if you support them, arrive as additional lines with status: "countered" and an in_response_to naming the line they answer. Adding counters later is a non-breaking climb; see Negotiation.
• Your statuses map onto the canonical state machine. Buyers never see your wire format, only marketplace state.

Idempotency and replay

Every submission carries an order_id and an order_version. The version identifies a revision of intent, never a retry: we bump it only when the order's content changes on purpose.

• On a duplicate (order_id, order_version), replay your stored response verbatim. Do not re-run order logic and do not error: the replay is how we learn the outcome of a request we never got an answer to.
• The public API holds itself to the same rule: a buyer resubmitting an identical order gets the original response back, and 409 is reserved for a real conflict. See API conventions.

Decision delivery

Three rungs; declare the ones you offer and we adapt.

GET/healthyour host

GET https://api.acmebroadcasting.example/switchboard/health

200 {
  "status": "ok",
  "protocol_version": "v1",
  "capabilities": { "rate_card_distribution": null, "live_avails": null }
}

Capabilities you do not support yet ship as declared-but-null. When your rate feed or live avails go live, the slot flips and the platform starts using it; nothing else changes.

What we need from you

• Auth. An OAuth2 client-credentials grant is the standard ask: a token endpoint plus a client ID and secret issued to us. An API key works if that is what your stack issues. Credentials sit in managed key storage on our side and rotate quarterly.
• Allowlisting. Mutual IP allowlists on request; mTLS as optional hardening.
• SLAs. Your decision latency and lead-time rules live in your capability profile (for example: orders need 48 hours before first air), so the platform never submits what you cannot decide in time.
• A test environment. A sandbox host we can point the connection at before production traffic.