---
url: https://docs.dataflair.ai/marketplace/ad-server-api/inventory.md
description: >-
  How a bookable ad slot on your platform is identified, and how DataFlair
  learns about your slots so an operator can map them to placements.
---

# Inventory identity

How a bookable ad slot on your platform is identified. Also how DataFlair learns about your slots, so an operator can map them to DataFlair placements.

## The `inventory_id`

Every bookable ad slot has a **stable, opaque id**. DataFlair calls it `inventory_id`. It is the one reference that ties a DataFlair placement to a real slot in your ad server. It appears in:

* [`POST /forecast`](/marketplace/ad-server-api/operations/forecast): "how many impressions can this slot deliver?"
* [`POST /orders`](/marketplace/ad-server-api/operations/orders): "book this slot for this advertiser."

Requirements:

* **Stable.** Once DataFlair has mapped a placement to an `inventory_id`, that id must keep pointing at the same slot. Do not recycle ids across deleted and recreated slots.
* **Opaque.** It can be any string: a numeric id, a slug or a UUID. DataFlair treats it as a token and does not parse it.
* **Yours.** You mint it. DataFlair stores it against a placement. It plays the same role as `gam_ad_unit_id` for GAM or `revive_zone_id` for Revive.

## Listing your inventory

To map placements without an operator copying ids by hand, expose a read endpoint that lists your bookable slots: [`GET /inventory`](/marketplace/ad-server-api/operations/inventory). It is part of the required contract. While you are still building it, an operator can enter `inventory_id` values by hand during placement mapping. Treat that as an onboarding stopgap.

DataFlair uses the equivalent read on Google Ad Manager (reading ad units) and on Revive (listing zones).

## Sizes and formats

* **Sizes** matter because a line item's creative must fit the slot. DataFlair checks the booked creative size against the slot's `sizes` before it traffics the creative. Its GAM integration does an exact pixel check. Return every size a slot accepts.
* **Format** lets DataFlair keep a video slot out of a display booking. Keep the vocabulary consistent across slots.

## Mapping happens in DataFlair

You expose the ids. An operator does the mapping of placements to slots inside DataFlair after connecting, on the Placements screen. Your job is to make the ids **discoverable** (`GET /inventory`) and **stable**. DataFlair skips an unmapped placement at booking time. It does not guess, so nothing books against the wrong slot.