Ad Server API overview

You run your own ad server. You build a small REST and JSON API on it. DataFlair calls that API. You do not call DataFlair.

What is live today

When you connect, and each time you click Verify, DataFlair calls GET /health and GET /inventory. The forecast, booking and reporting endpoints are part of the contract. DataFlair does not call them yet, and this page will say when each one goes live.

Roles

Actor	Who	Role in the integration
DataFlair	The platform your advertiser demand comes from	The client of your API. It calls your endpoints. You do not call it.
Your ad server	Your custom platform	The server. It owns inventory, serves ads and counts delivery. You expose the API this section describes.
Advertiser	A buyer on DataFlair	Browses your inventory, books it and pays into a DataFlair wallet. The advertiser does not talk to your platform.
Your ad-ops	A person on your side	Reviews the draft DataFlair pushes and takes it live in your own console.

The pull model

DataFlair starts every request, over HTTPS. Your platform is a normal REST and JSON server that answers. There are no webhooks for you to call and no DataFlair SDK to embed. The core flow needs no callback into DataFlair.

   Advertiser demand                     Your ad server (you build this API)
   ─────────────────                     ────────────────────────────────────
   DataFlair  ── HTTPS ──▶   GET  /health         (connect and verify)
              ── HTTPS ──▶   GET  /inventory       (map ad slots)
              ── HTTPS ──▶   POST /forecast        (availability)
              ── HTTPS ──▶   POST /orders          (push a draft booking)
              ── HTTPS ──▶   POST /reports         (pull delivery)

That is the whole surface. Five endpoints. Four are read-only or read-mostly. One, POST /orders, writes a draft. All five are required, and a production integration implements the full set.

During onboarding, an operator can enter slot ids by hand until GET /inventory is live (see Inventory identity). Treat that as a stopgap.

Lifecycle

1. Connect (once). DataFlair calls your API.
   • GET /health with your credential returns 200 with the account, timezone, currency and capabilities.
   • GET /inventory returns your ad slots with their ids and sizes.
   • An operator maps DataFlair placements to your slot ids.
2. An advertiser is booking. DataFlair calls your API.
   • POST /forecast with a slot, dates and geo returns available_impressions and forecasted_impressions.
3. You approve the booking in DataFlair. DataFlair calls your API.
   • POST /orders with the advertiser and the lines. Your API creates the order and the line items as drafts, and returns 201 with order_id, the line_item_id values and status: DRAFT.
4. Go live (a person, on your side). Your ad-ops review the draft and activate it in your own console.
5. Reconcile (repeating). DataFlair calls your API.
   • POST /reports with line ids and a date range returns impressions and clicks per line.

The three capabilities

1. Availability and forecast. POST /forecast. Given a slot, a flight window and optional targeting, return how many impressions are available and forecasted. This lets an advertiser book a sensible amount. See POST /forecast.
2. Campaign reporting. POST /reports. Given the line ids DataFlair created, or an order id, and a date range, return impressions and clicks per line. DataFlair reconciles a campaign by matching these lines to the booked slots. See POST /reports.
3. Save a reservation as a draft. POST /orders. Given an approved booking, create an order and one draft line item per booked inventory line (ad slot, geo and month), and return your stable ids. See POST /orders.

Two more pieces connect these: authentication (a key you issue to DataFlair) and inventory identity (a stable id per bookable ad slot).

The draft-only rule

DRAFT ONLY

POST /orders creates draft, paused or inactive objects only. DataFlair does not call activate, approve, go-live, unpause or publish. None of them is in the adapter, by design. A person in your console decides whether inventory serves.

DataFlair follows the same rule for Google Ad Manager. It creates DRAFT orders and does not call performOrderAction. It follows the rule for Revive too. It creates banners as INACTIVE and does not link them to a zone. Your platform is the third ad server under the same rule. The full rule is on POST /orders.

Environments

Give DataFlair two base URLs if you can: a sandbox that is safe for test drafts, and production. DataFlair marks a capability as verified only after it has exercised it against your API. A sandbox lets both sides prove the integration before real money moves. One environment also works. The first verification then runs against production.