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)
Placement	Ad slot	DataFlair stores your slot's inventory_id on the placement (Inventory identity)
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.
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.