---
url: https://docs.dataflair.ai/marketplace/ad-server-api/overview.md
description: >-
  The five endpoints your own ad server exposes so DataFlair can list inventory,
  forecast it, book drafts and pull delivery.
---

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

::: info 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.

```text
   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](/marketplace/ad-server-api/inventory)). Treat that as a stopgap.

## Lifecycle

1. **Connect** (once). DataFlair calls your API.
   * [`GET /health`](/marketplace/ad-server-api/operations/health) with your credential returns `200` with the account, timezone, currency and capabilities.
   * [`GET /inventory`](/marketplace/ad-server-api/operations/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`](/marketplace/ad-server-api/operations/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`](/marketplace/ad-server-api/operations/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`](/marketplace/ad-server-api/operations/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](/marketplace/ad-server-api/operations/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](/marketplace/ad-server-api/operations/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](/marketplace/ad-server-api/operations/orders).

Two more pieces connect these: [authentication](/marketplace/ad-server-api/authentication) (a key you issue to DataFlair) and [inventory identity](/marketplace/ad-server-api/inventory) (a stable id per bookable ad slot).

## The draft-only rule

::: danger 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](/marketplace/ad-server-api/operations/orders#draft-only).

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