Appearance
API reference
The full OpenAPI contract for the Ad Server API. The overview walks through the same endpoints in prose.
The server URL below uses a host variable. Set it to the host of your own ad server. DataFlair calls your server. You do not call DataFlair.
The REST/JSON contract a publisher's custom ad server exposes so DataFlair can integrate it, alongside its existing Google Ad Manager and Revive integrations. DataFlair is the client; your ad server is the server. Five endpoints: connect/verify (GET /health), inventory discovery (GET /inventory), availability forecast (POST /forecast), draft booking (POST /orders), and delivery reporting (POST /reports). Invariant: POST /orders creates DRAFTS ONLY. DataFlair does not activate inventory.
Contact
Servers
https://{host}/api/v1Your own ad server. DataFlair calls this base URL.
Connect & verify probe
GET
/health
Read-only. Confirms the credential works and returns account context (timezone, currency) plus the capabilities this platform supports.
Authorizations
bearerAuth
A single static bearer token (API key) the publisher issues to DataFlair and DataFlair sends on every request. No OAuth flow. Least-privilege (read + create-draft + report), revocable, HTTPS only.
Type
HTTP (bearer)
Responses
Account reachable and readable.
application/json
JSON "account_id": "acct_1029", "account_name": "Example Media Network", "timezone": "Europe/Berlin", "currency": "EUR", "capabilities": { "forecast": true, "reporting": true, "draft_booking": true }
{
}
GET
/health
Samples
List bookable ad slots
GET
/inventory
Cursor-paginated list of ad slots DataFlair can map placements to.
Authorizations
bearerAuth
A single static bearer token (API key) the publisher issues to DataFlair and DataFlair sends on every request. No OAuth flow. Least-privilege (read + create-draft + report), revocable, HTTPS only.
Type
HTTP (bearer)
Parameters
Query Parameters
limit
Type
integer
Default
50Minimum
1Maximum
200cursor
Type
string
Responses
A page of ad slots.
application/json
JSON "data": [ { "inventory_id": "slot_728x90_home", "name": "Homepage Leaderboard", "sizes": [ [ "728x90", "970x250" ] ], "format": "display", "status": "active" } ], "next_cursor": "string"
{
}
GET
/inventory
Samples
Availability & forecast for one slot
POST
/forecast
Read-only, creates nothing. Returns available and forecasted impressions for a slot over a flight, with optional geo targeting. Return 501 if this slot cannot be forecast; declare "forecast": false in /health if the platform cannot forecast at all (DataFlair then does not call this).
Authorizations
bearerAuth
A single static bearer token (API key) the publisher issues to DataFlair and DataFlair sends on every request. No OAuth flow. Least-privilege (read + create-draft + report), revocable, HTTPS only.
Type
HTTP (bearer)
Request Body
application/json
JSON "inventory_id": "slot_728x90_home", "flight": { "start_date": "2026-08-01", "end_date": "2026-08-31" }, "targeting": { "geo": [ [ "DE", "AT" ] ] }, "sizes": [ "string" ]
{
}
Responses
Forecast result.
application/json
JSON "inventory_id": "slot_728x90_home", "available_impressions": 1420000, "forecasted_impressions": 2100000, "unit_type": "IMPRESSIONS"
{
}
POST
/forecast
Samples
Save an approved reservation as a DRAFT order
POST
/orders
Creates an order and one DRAFT line item per booked inventory line (ad slot x geo x month). MUST create drafts only and MUST NOT activate anything. Retry-safe by idempotency_key: a repeat with the same key and the same body returns the same order_id and line_item_ids and creates nothing new; the same key with a different body is a 409. To update an order/line you already created (e.g. attach a creative once approved), send a new idempotency_key with the same order.external_ref / line_items[].external_ref; match on external_ref and return 200 with the existing ids.
Authorizations
bearerAuth
A single static bearer token (API key) the publisher issues to DataFlair and DataFlair sends on every request. No OAuth flow. Least-privilege (read + create-draft + report), revocable, HTTPS only.
Type
HTTP (bearer)
Parameters
Header Parameters
Idempotency-Key*
Same value as the body's idempotency_key.
Type
Requiredstring
Request Body
application/json
JSON "idempotency_key": "DF-CMP-VDWZQ4IT", "advertiser": { "name": "Acme Corp", "external_ref": "brand_5501" }, "order": { "name": "Summer Launch (DF-CMP-VDWZQ4IT)", "external_ref": "CMP-VDWZQ4IT" }, "line_items": [ { "external_ref": "DF-CMP-VDWZQ4IT-329", "inventory_id": "slot_728x90_home", "flight": { "start_date": "2026-08-01", "end_date": "2026-08-31" }, "goal_impressions": 100000, "targeting": { "geo": [ [ "DE", "AT" ] ] }, "sizes": [ "string" ], "creatives": [ { "type": "third_party_tag" } ] } ]
{
}
Responses
Either an idempotent replay (same key, same body) or an update to an existing order/line matched by external_ref (new key, same external_ref). Same ids returned either way.
application/json
JSON "order_id": "ord_55021", "status": "DRAFT", "line_items": [ { "external_ref": "DF-CMP-VDWZQ4IT-329", "line_item_id": "li_88012", "status": "DRAFT" } ]
{
}
POST
/orders
Samples
Delivery report, per line item
POST
/reports
Returns ad-server impressions and clicks per line_item_id over a date range. DataFlair reconciles by line_item_id, so the id must be the one returned by POST /orders and must be stable across renames/edits.
Authorizations
bearerAuth
A single static bearer token (API key) the publisher issues to DataFlair and DataFlair sends on every request. No OAuth flow. Least-privilege (read + create-draft + report), revocable, HTTPS only.
Type
HTTP (bearer)
Request Body
application/json
JSON
"string"
Responses
Delivery rows.
application/json
JSON "rows": [ { "line_item_id": "li_88012", "date": "string", "impressions": 98240, "clicks": 173 } ], "next_cursor": "string"
{
}
POST
/reports