Basics
sellers.json explained: fields, seller types and how to read one
By Stoqlab Research · Updated · 6 min read
app-ads.txt is the publisher saying who may sell its inventory. sellers.json is the other side: each SSP, exchange or ad network listing every account it pays, and who is behind it. A buyer who reads both can tell whether the account in a bid request belongs to the app's owner or to a reseller, and whether that matches what the publisher declared.
The format is the IAB Tech Lab sellers.json specification, version 1.0. The file lives at
/sellers.json on the same domain the network asks publishers to use in field #1 of app-ads.txt, so
pubmatic.com lines are checked against https://pubmatic.com/sellers.json.
What is in the file
{
"version": "1.0",
"contact_email": "…",
"identifiers": [{ "name": "TAG-ID", "value": "…" }],
"sellers": [
{ "seller_id": "4821", "seller_type": "PUBLISHER", "name": "Example Games Ltd", "domain": "examplegames.example" },
{ "seller_id": "7730", "seller_type": "INTERMEDIARY", "name": "Example Mediation", "domain": "mediation.example" },
{ "seller_id": "9102", "seller_type": "PUBLISHER", "is_confidential": 1 }
]
}
Top level: version (required, "1.0"), sellers (required), and optionally contact_email,
contact_address and identifiers such as the network's TAG ID or a D-U-N-S number. The specification
requires every seller to be listed, including confidential ones.
The seller fields
| Field | Meaning |
|---|---|
seller_id | Required. The account ID: the same value as field #2 of app-ads.txt and sid in the SupplyChain object. |
seller_type | Required. PUBLISHER, INTERMEDIARY or BOTH (below). |
name | The legal entity paid for inventory sold under the account. Required unless confidential. |
domain | That entity's business domain. Required unless confidential or the seller has no web presence. |
is_confidential | Optional, default 0. With 1, name and domain are left out. |
is_passthrough | Optional, default 0. Marks a seller that passes inventory from its source on to the next system while keeping its own account there. Rarely used. |
comment | Optional free text, useful when one company has several accounts. |
PUBLISHER, INTERMEDIARY, BOTH
- PUBLISHER: the seller owns the inventory and the network pays it directly. An app developer's own account.
- INTERMEDIARY: the seller does not own the inventory, or is not paid directly as its owner. Resellers, ad networks and mediation companies selling other publishers' apps.
- BOTH: the account carries both kinds. A buyer cannot tell from the file which one applies to a given request.
How a line is checked against it
For a line pubmatic.com, 4821, DIRECT in an app's app-ads.txt, a verifier:
- fetches pubmatic.com's sellers.json;
- looks for
seller_id4821. Not there: the line points to an account the network does not (or no longer) pay. Buyers drop such paths; - compares the type with the relationship: DIRECT should be a
PUBLISHER, RESELLER anINTERMEDIARY. A mismatch usually means the line or the network's listing is wrong; - for DIRECT, may compare the seller's
domainwith the app's developer domain or its OWNERDOMAIN. A match confirms the line both ways.
An INTERMEDIARY's domain often belongs to another network with its own sellers.json. Following it gives the next hop of the declared path: see How to read a supply path.
Confidential sellers
Confidentiality exists for sellers with a legitimate reason not to be named, but a confidential entry tells a buyer only that the account exists. Many buyers treat a high share of confidential sellers as a reason to prefer other paths. The network directory shows each network's confidential share next to its seller counts.
Look one up
The sellers.json validator checks a network's file against the specification, and the seller ID lookup finds an account across the networks we read. Network pages, such as PubMatic's, summarise each file: seller types, confidential share and how the lines naming the network check out.