What is buyers.json, and what does the DemandChain object add?
Part of Supply path transparency
The short answer
buyers.json is a public JSON file that a DSP or other buying intermediary posts at /buyers.json on its root domain, listing the buyer seats it represents. The DemandChain object travels in each bid response and lists, in order, the parties paying for that creative. Together they give sellers the buy side view that sellers.json and schain give buyers.
Key takeaways
- IAB Tech Lab released buyers.json and the DemandChain object as version 1.0 in June 2021, to help sellers trace malvertising to the buyer.
- A buyers.json entry pairs a buyer_id with a buyer_type of ADVERTISER, INTERMEDIARY or BOTH, and the same ID should appear as the seat in the bid response.
- Agencies are expected to publish their own buyers.json on the corporate domain; brands that pay directly have nothing to implement, only a domain to share.
- No public adoption measure exists; in October 2026, 26 of 796 Prebid bidder adapter pages declared DemandChain support.
What is buyers.json?
Definition
- buyers.json
- A JSON file that an advertising system or other intermediary between the payer and the publisher posts on its root domain to declare publicly the buyers it represents, each with an ID, a type and, unless marked confidential, a legal name and domain.
The buyers.json 1.0 specification (opens in a new tab), released in June 2021, says it "enables sellers to identify who is buying their inventory." The stated driver is malvertising: bad actors jump from DSP to DSP, and publishers and SSPs cannot block one known bad entity across all of its access points at once.
The access rules mirror the sell side files. The file sits at https://{root_domain}/buyers.json, where the root domain is the public suffix plus one string, served over HTTPS as application/json. A consumer may follow one redirect off the original root domain, and without cache directives should default to an expiry of 7 days.
| Field | Status in the spec | What it holds |
|---|---|---|
| buyers | Required | The Buyers objects the system represents; all buyers must be included even if they are confidential |
| identifiers | Optional | IDs for the advertising system itself, such as a TAG-ID or a Dun & Bradstreet DUNS number |
| contact_email and contact_address | Optional | Who to ask about the file, and the system's business address |
| version | Required | Who to ask about the file, and the business address |
| last_updated | Recommended | When the contents last changed, in ISO 8601 UTC, left alone if nothing changed |
What does one entry in a buyers.json file tell a seller?
Each entry in the buyers array identifies the legal entity that pays for inventory bought under that buyer_id. The spec says that in most cases a buyer_id should represent only a single legal entity; a managed service desk buying for several clients under one seat must post its own buyers.json and appear as its own node.
| Field | Rule in the spec | What a reader learns |
|---|---|---|
| buyer_id | Required; should match the seat in the OpenRTB bid response and the bsid in the DemandChain | The key that joins the file to live bids |
| buyer_type | Required; ADVERTISER, INTERMEDIARY or BOTH, read case insensitively | Whether the advertiser or an agency or reseller controls the seat |
| is_confidential | Optional; 0 by default, 1 hides the identity | That a seat exists even when its owner is withheld |
| name and domain | Required unless confidential; domain is a root domain, never a URL | The legal entity that pays under the ID |
| comment | Optional | What a second or third seat for the same buyer is for |
| created_on | Recommended; an ISO 8601 date | Seat age; the spec notes malvertising buyers tend to have a short lifespan |
What is the DemandChain object?
The DemandChain Object 1.0 specification (opens in a new tab), or dchain, lets sellers see all parties involved in buying the creative in a given bid response. It sits in BidResponse.seatbid.bid.ext.dchain in OpenRTB 2.5 or later. It is an extension: the OpenRTB 2.6 specification (opens in a new tab) has no native dchain field, only seat, the ID of the buyer seat on whose behalf a bid is made.
The object holds three required attributes. complete is 1 when the chain reaches back to the ultimate source of payment for the creative, and 0 when it does not. nodes lists the parties in order, from the first known payer to the entity sending the response. ver carries "1.0". Each node names asi, the buying system's domain, which should host a buyers.json file, and bsid, which must appear as a buyer_id in that file.
The spec's rules for building a dchain
- Start the chain at the first system. The originating system creates a node for itself and sets complete to 1 only if it can name the ultimate payer.
- Mark gaps honestly. If payers are known to exist beyond the listed nodes, complete must be 0.
- Append, never copy. A system passing a response along keeps the original complete value and adds its node at the end.
- Repair broken chains. A response with no dchain, or an invalid one, gets a new object with complete set to 0.
How do buyers.json and sellers.json relate?
In many ways, buyers.json and DemandChain Object can be considered the mirror images of sellers.json and SupplyChain Object, with the goal of providing a similar level of transparency to publishers, just as sellers.json & SupplyChain Object had provided transparency to buyers.
| Question | Sell side answer | Buy side answer |
|---|---|---|
| Static directory | sellers.json, posted by each advertising system | buyers.json, posted by each DSP or buying intermediary |
| Per transaction record | SupplyChain object in the bid request | DemandChain object in the bid response |
| Join key | seller_id, equal to the ads.txt account ID and the schain sid | buyer_id, equal to the response seat and the dchain bsid |
| Role labels | PUBLISHER, INTERMEDIARY or BOTH | ADVERTISER, INTERMEDIARY or BOTH |
| Main reader | Buyers and DSPs checking who sells | Publishers, SSPs and ad quality teams checking who buys |
The pairs share structure but not direction: sellers.json (opens in a new tab) answers who is paid for inventory, buyers.json who pays for the ad. The sellers.json guide and SupplyChain object guide cover the sell side.
Who publishes a buyers.json file?
The implementation guide assigns a job to each kind of participant, following the spec's line that all intermediaries between the buyer and publisher should publish a buyers.json file.
| Participant | Publishes buyers.json? | Other tasks in the guide |
|---|---|---|
| DSP, the first programmatic access point | Yes, on its advertising system domain | Start dchain in bid responses, expose seat IDs, tag ad markup with the creative source |
| DSP managed service desk | Yes, a separate file on a domain for the desk | Appear as its own node; the DSP's file points to the desk's seat |
| SSP or other intermediary | Yes, when it acts as a buying intermediary | Extend or start dchain on responses it passes |
| Agency or holding company | Yes, on its corporate domain, listing the brands it represents | Give DSPs that domain to put in their files |
| Brand paying directly | No specific implementation | Share one canonical domain with agencies and DSPs |
| Publisher or app developer | No | Train ad ops to read the creative source string; push partners to adopt |
An agency runs no ad server, so the guide suggests an internal account ID as buyer_id for each brand relationship, and one corporate domain at each DSP. A brand buying for another payer is, in the guide's words, effectively acting as an agency. The buyer seat ID guide and the DSP explainer cover the seat side.
How far has buyers.json and DemandChain adoption gone?
No issuer publishes an adoption rate. IAB Tech Lab's supply chain standards directory (opens in a new tab) still lists the pair at version 1.0, dated June 2021. The Tech Lab blog announcing the 1.0 release (opens in a new tab) named two obstacles: contractual concerns about exposing business relationships, and "a lack of consistency in identifying buyers."
One public trace sits in header bidding. Prebid.js has a Demand Chain Object module (opens in a new tab) that validates dchain data from bidders, rejects invalid objects in its default strict mode, and appends a node for itself. When checked on October 22, 2026, 26 of 796 bidder adapter pages in Prebid's documentation declared dchain support. That counts documentation flags, not live traffic.
What does a buyers.json rollout look like for an agency?
Fictional example
An agency lists a cosmetology school group in Kentucky
An unnamed independent agency in Louisville buys display and online video for an unnamed cosmetology and barbering school group with campuses in Louisville and Lexington, on beauty, career and local news sites. A publisher's ad ops team reports a creative using the school's logo that the agency never trafficked.
The captured creative source string names a DSP domain, a seat and a creative ID. That DSP's buyers.json lists the seat as INTERMEDIARY under a name the agency does not recognize, created two weeks earlier; the agency's own seat is listed separately under its corporate domain.
The agency then publishes its own buyers.json listing the school group as ADVERTISER under an internal account ID, and sends its domain to each DSP it buys through. Sellers can now tell the seats apart.
Buy side transparency checklist for an agency
- Our corporate domain serves /buyers.json over HTTPS with Content-Type application/json and version "1.0".
- Each brand has its own buyer_id, legal name, root domain and created_on date.
- No entry is marked confidential without a written reason we could defend to a seller.
- Each DSP we buy through has our corporate domain and lists our seat as INTERMEDIARY.
- Ad ops knows how to read a data-ad-creative-source string and look the seat up in the DSP's buyers.json.
Where does PlacementGraph fit alongside buy side transparency?
buyers.json helps sellers see who buys. A buyer planning a site list still needs the other direction: who sells each site, and how.
Frequently asked questions
Does an agency's buyers.json show which publishers or DSPs it works with?
No. The implementation guide says buyers.json files designate account relationships in the direction of the payer, meaning which agencies or advertisers a system receives demand from. An entry on an agency's file does not represent a relationship with an inventory provider or with a DSP.
What is the data-ad-creative-source string?
It is a comma separated string the DemandChain spec recommends placing in ad markup: version, DSP domain, buyer seat ID and creative ID, for example 1.0,mydsp.example,ac1f9e,89708971. Publisher ad ops staff who capture a problem creative can append /buyers.json to the DSP domain and look up the seat.
How quickly should a buyers.json file change when a new buyer is added?
The implementation guide says the file should be updated whenever buyers that may appear in bid responses are added, and no more than one day thereafter. Hosts should not reuse an old seat ID for a new entity, except for a name change, merger or acquisition.
Does buyers.json name the brand behind an ad?
Not always. A brand appears only if the system or agency lists it, and a seat can be marked confidential. The DemandChain spec lets a confidential entry be disclosed privately through the name and domain fields of a node in individual bid responses, and lets non programmatic payers appear with a name and domain only.
Sources
- buyers.json and DemandChain Object (opens in a new tab)IAB Tech Lab
- buyers.json Specification Version 1.0 (June 2021) (opens in a new tab)IAB Tech Lab
- DemandChain Object Specification Version 1.0 (June 2021) (opens in a new tab)IAB Tech Lab
- Implementation Guide for buyers.json and DemandChain Object (June 2021) (opens in a new tab)IAB Tech Lab
- The Time for Buy-side Transparency is Now (opens in a new tab)IAB Tech Lab
- Supply Chain Foundations standards directory (opens in a new tab)IAB Tech Lab
- OpenRTB 2.6 specification, SeatBid object (opens in a new tab)IAB Tech Lab
- sellers.json specification (opens in a new tab)IAB Tech Lab
- Module: Demand Chain Object (opens in a new tab)Prebid.org
- Certified Against Malvertising (opens in a new tab)Trustworthy Accountability Group
Researched and written by PlacementGraph Research. Read how we research, source and update these pages. Corrections: diana@placementgraph.com.