sellers.json

IAB Tech Lab sellers.json specification for ads.txt supply chain transparency.

Type object
File match sellers.json **/sellers.json
Schema URL https://catalog.lintel.tools/schemas/ads/sellers/latest.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Schema for the IAB Tech Lab sellers.json specification (v1.0, July 2019).

sellers.json provides a mechanism for advertising systems to publicly declare the sellers that they represent and those sellers' identifiers within their systems, enabling buyers to discover who the entities are that are either direct sellers of or intermediaries in the selling of digital advertising.

A published and accessible sellers.json file allows:

  • The identity of the final seller of a bid request to be discovered (assuming they are ads.txt authorized)
  • The identities of all nodes (entities that participated in the bid request) in the SupplyChain object to be discovered
  • Smaller bid request object sizes by allowing information to be looked up and cached offline

Access method

The file must be hosted at the root domain of the advertising system at the path /sellers.json (e.g. <https://example.com/sellers.json>). The root domain is defined as the public suffix plus one string in the name per the Public Suffix List. The file may also be hosted on subdomains as needed.

The response must include Content-Type: application/json (optionally with ; charset=utf-8). HTTPS is preferred over HTTP.

Caching

Consumers should respect standard HTTP cache-control headers (Expires, Cache-Control). If no cache directives are present, a 7-day default expiry should be used.

See the sellers.json specification (PDF) for the full reference. Licensed under Creative Commons Attribution 3.0 by the OpenRTB Working Group.

Properties

sellers Seller[] required

The list of all Seller objects represented by the advertising system. All sellers must be included even if they are confidential (with is_confidential set to 1).

version string required

The version of the sellers.json specification. Currently the only valid value is "1.0".

Constant: "1.0"
identifiers Identifier[]

Array of Identifier objects associated with this advertising system. Examples include TAG-IDs, Dun & Bradstreet DUNS numbers, or any custom identifier that a consuming advertising system might need.

See Identifier Names for standard identifiers.

contact_email string

An email address to contact the advertising system for questions or inquiries about this file.

format=email
contact_address string

The business address of the advertising system.

ext object

Placeholder for advertising-system-specific extensions to this object.

Definitions

Seller object

The identification of a selling legal entity that is paid for inventory sold on behalf of seller_id.

It is invalid for a seller_id to represent multiple entities — every seller_id must map to only a single entity that is paid for inventory transacted with that seller_id. It is valid for a selling entity to have multiple seller_id values within an advertising system (e.g. separate IDs for different regions or inventory types).

seller_id string required

The identifier associated with the seller or reseller account within the advertising system. This is the same ID that appears in:

  • An ads.txt file
  • The SupplyChain .nodes array sid property
  • In most cases, the Publisher.Id property of an OpenRTB bid request
seller_type string required

An enumeration of the type of account. This field should be treated as case-insensitive when interpreting the data.

  • PUBLISHER — The inventory sold through this account is on a site, app, or other medium owned by the named entity and the advertising system pays them directly.
  • INTERMEDIARY — The inventory sold through this account is not owned by the named entity or the advertising system does not pay them directly.
  • BOTH — Both types of inventory are transacted by this seller.
Values: "PUBLISHER" "INTERMEDIARY" "BOTH"
is_confidential integer

Indicates whether the identity of the seller is confidential.

  • 0 — Not confidential (default). name and domain must be provided.
  • 1 — Confidential. name and domain may be omitted.
Default: 0
Values: 0 1
is_passthrough integer

Indicates whether the seller is a passthrough partner — a facilitator of inventory from the upstream supplier to the consumer of the inventory. The upstream supplier and consumer must establish a business relationship with each other such that the upstream supplier has control of their account within the consumer's platform.

When set to 1:

  • This seller has an account control relationship with the downstream/consuming advertising system
  • If this seller is the last link in a SupplyChain, the buying system must have established an account control relationship with this seller to transact the seller's inventory
  • If this is not the last link in a SupplyChain, this seller should exist between two entities that have an account control relationship

When set to 0 (default):

  • The downstream/consuming advertising system has no account control relationship with this seller
Default: 0
Values: 0 1
name string

The name of the company (the legal entity) that is paid for inventory transacted under the given seller_id.

Required when is_confidential is 0 (the default). May be omitted only when is_confidential is set to 1.

domain string

The business domain name of the company (the legal entity) that is paid for inventory transacted under the given seller_id.

This should be the root domain only (public suffix plus one label, e.g. example.com), not a full URL. Implementers should use the Public Suffix List to derive the root domain. When seller_type is INTERMEDIARY or BOTH, this should be the root domain of the seller's own sellers.json file.

Required if the seller has a web presence and is_confidential is 0. May be omitted when is_confidential is 1 or when the seller has no web presence.

comment string

Any helpful description for this inventory. Useful for sellers that have multiple seller_id values to describe what each seller_id represents (e.g. regional inventory, O&O vs. non-O&O).

ext object

Placeholder for advertising-system-specific extensions to this object.

Identifier object

An arbitrary name/value pair used to communicate common values such as business identifiers, certification identifiers, or any other identifier that a consuming system might need to better interoperate with the seller.

Standard identifier names

name string required

The identifier type name (referred to in the spec as "the description of the identifier"). See the standard identifier names table above.

Examples: "TAG-ID", "DUNS"
value string required

The value of the identifier.

Examples: "28cb65e5bbc0bd5f"

Examples

{
  "contact_email": "[email protected]",
  "contact_address": "Advertising System Inc., 101 Main Street, New York, NY 10101",
  "version": "1.0",
  "identifiers": [
    {
      "name": "TAG-ID",
      "value": "28cb65e5bbc0bd5f"
    }
  ],
  "sellers": [
    {
      "seller_id": "1942009976",
      "name": "Publisher1",
      "domain": "publisher1.com",
      "seller_type": "PUBLISHER"
    },
    {
      "seller_id": "1397382429",
      "name": "Exchange1",
      "domain": "exchange1.com",
      "seller_type": "INTERMEDIARY"
    },
    {
      "seller_id": "20000000",
      "name": "Seller And Intermediary, Inc",
      "domain": "sellerandintermediary.com",
      "seller_type": "PUBLISHER",
      "comment": "NorthAmerica O&O inventory"
    },
    {
      "seller_id": "20000001",
      "name": "Seller And Intermediary, Inc",
      "domain": "sellerandintermediary.com",
      "seller_type": "PUBLISHER",
      "comment": "APAC O&O inventory"
    },
    {
      "seller_id": "20000002",
      "name": "Seller And Intermediary, Inc",
      "domain": "sellerandintermediary.com",
      "seller_type": "INTERMEDIARY",
      "comment": "Non O&O inventory"
    },
    {
      "seller_id": "101010101",
      "name": "Hybrid Seller",
      "domain": "hybridseller.com",
      "seller_type": "BOTH",
      "comment": "Sells both O&O and other sellers' inventory"
    },
    {
      "seller_id": "00000001",
      "seller_type": "INTERMEDIARY",
      "is_confidential": 1
    },
    {
      "seller_id": "EB_0001",
      "name": "Passthrough Publisher",
      "domain": "passthroughpublisher.com",
      "seller_type": "PUBLISHER",
      "is_passthrough": 1,
      "comment": "direct buyer/seller of this inventory must establish an account relationship with Passthrough Publisher"
    }
  ]
}