---
url: https://docs.dataflair.ai/marketplace/ad-server-api/concepts.md
description: >-
  The vocabulary DataFlair and your ad server share, and how DataFlair entities
  map onto your platform's objects.
---

# Concepts and entity mapping

DataFlair and your ad server use different nouns for the same reality. This page fixes the vocabulary and maps one side onto the other, so the JSON fields in the endpoint pages are unambiguous.

## Glossary

| DataFlair term | Meaning | Your platform's likely equivalent |
| --- | --- | --- |
| **Publisher** | The organisation that owns the inventory. In this integration, that is you. | Your account or network |
| **Property** | A website, app or channel a publisher owns. A grouping only. | Site or domain (often no direct object) |
| **Placement** | A durable, named ad slot on a property, for example "Homepage Leaderboard 728x90". | **Ad slot, ad unit or zone** |
| **Inventory cell** | A bookable slice: one placement, one geo (or region) and one calendar month, with an impression pool and a price. | No single object. It becomes one line item's targeting, flight and goal. |
| **Advertiser or brand** | The buyer a campaign is booked for. | **Advertiser** |
| **Reservation** | A booking request an advertiser submits and you approve. It lives entirely in DataFlair. | No object. It comes before anything reaches your platform. |
| **Campaign** | What a reservation becomes once approved. DataFlair pushes it to your ad server. | **Order** (a container for line items) |
| **Line item** | One booked inventory cell, trafficked into your platform. | **Line item, flight, or banner with targeting** |
| **Delivery report** | Impressions and clicks pulled back from your ad server to reconcile a campaign. | **Report or statistics** |

## The core mental model

> A DataFlair campaign is one order on your platform. Each booked inventory cell is one line item inside it. Each line item targets one ad slot, for one month, with one impression goal, and optionally one geo.

DataFlair already uses this model for Google Ad Manager (campaign to order, cell to line item, placement to ad unit) and for Revive (campaign to campaign, cell and creative to banner, placement to zone). Your platform has the same shape with your own names.

## Entity mapping

| DataFlair entity | Maps to (your platform) | How it links |
| --- | --- | --- |
| Publisher **connection** (your base URL and credential) | Your **account or network** | One connection per publisher, made when you connect ([Authentication](/marketplace/ad-server-api/authentication)) |
| **Placement** | **Ad slot** | DataFlair stores your slot's `inventory_id` on the placement ([Inventory identity](/marketplace/ad-server-api/inventory)) |
| **Inventory cell** (placement, geo, month) | No single object | Becomes one line item's `inventory_id` target, `flight`, `goal_impressions` and `geo` |
| **Advertiser or brand** | **Advertiser** | You resolve or create an advertiser by the `name` DataFlair sends |
| **Campaign** | **Order** | One campaign is one order. You return an `order_id`. |
| Booked cell (**line item**) | **Line item** | You return a stable `line_item_id`. DataFlair stores it. |
| **Delivery report** | **Report or statistics** | DataFlair pulls impressions and clicks per `line_item_id` |

### What has no object on your side

* **Property** and **reservation** do not reach your platform. A reservation is a booking inside DataFlair, before approval. DataFlair pushes a campaign only after you approve it. A property is a grouping of placements on the DataFlair side.
* **The inventory cell** has no object of its own. It is a line item that targets your ad slot for one month with one impression goal and an optional geo. DataFlair does not create a "cell" on your platform.

## The two ids that make reconciliation work

Two identifiers cross the boundary and must be **stable**.

1. **`inventory_id`** is your id for a bookable ad slot. DataFlair sends it in `POST /forecast` and in each line of `POST /orders`. You define it. DataFlair stores it against a placement. See [Inventory identity](/marketplace/ad-server-api/inventory).
2. **`line_item_id`** is your id for a line you created in `POST /orders`. You return it when you create the line. DataFlair stores it and sends it back in `POST /reports`. DataFlair reconciles delivery by this id, so it must survive renames and edits. Do not recycle it or change it for a booked line.

DataFlair reconciles Google Ad Manager by the immutable `LINE_ITEM_ID` for the same reason. A line item can be renamed in GAM without breaking reconciliation. Your `line_item_id` plays the same role.

## Statuses you should know

You do not need to mirror these statuses. They explain when each call happens.

* A **reservation** moves from `pending_review` to `approved` (or `rejected`). DataFlair pushes a campaign to you only when it is `approved`.
* A **campaign** is pushed while it is in a traffickable state: `awaiting_creative`, `scheduled` or `live`. A future-dated booking is still pushed as a draft, and its flight starts later.
* On your side, the one status change DataFlair cares about is draft to live. DataFlair does not perform it. Your ad-ops do.