Sellers.json and SupplyChain Object

Overview

Sellers.json and SupplyChain Object are IAB specifications aiming at increasing trust and transparency in programmatic advertising.
Sellers.json is a public file hosted by exchanges (SSPs, ad networks, other resellers); it lists the sellers operating on the exchange; for each seller, the file indicates whether it is selling inventory on publishers’ sites directly or indirectly.
The SupplyChain Object allows buyers to see all parties who are selling or reselling a given bid request. Each party is represented by a node in the SupplyChain Object. Buyers can cross reference each node in the SupplyChain Object against the data in sellers.json and ads.txt and gain insights and information about who the sellers in the supply chain are.

Specifications and resources

• IAB Sellers.json specification
• IAB FAQ for sellers.json and SupplyChain Object in OpenRTB
• OpenRTB SupplyChain Object on Github
• Equativ Blog Post “Let’s Talk Sellers.json and SupplyChain Object”
• Equativ’s own sellers.json file
• Ads.txt/App-ads.txt help article

Sellers.json

The sellers.json file lists the sellers operating on the exchange (SSPs, ad networks, other resellers) with the domain and name of each seller. Also, the file indicates for each seller, whether the seller is directly or indirectly selling inventory on publishers’ sites.
The sellers.json file can be seen as the exchange’s equivalent of publishers’ ads.txt file. The ads.txt file, hosted by publishers, contains the advertising systems (exchanges) and the account IDs on these advertising systems that are authorized to sell the inventory. However, ads.txt does not reveal the names (identity) of the entities associated with the account IDs: this information is included in the sellers.json file.

To implement the sellers.json specification, exchanges must host a file named “sellers.json” at the root level of their domain; for instance, Equativ’s own sellers.json file is hosted here.

The parent object is the container for all properties in the sellers.json file. It contains, among others:

• contact_email - the contact e-mail address of the advertising system
• contact_address - the business address of the advertising system 
• version - the version of the specification
• sellers - the list of all sellers, explained in detail below

For documentation on all items in the parent object see “Object: Parent” (page 6) in IAB sellers.json specification.

Here is an example of the parent object from Equativ’s own sellers.json file (hosted here):
 

{
    "contact_email": "quality-team@smartadserver.com",
    "contact_address": "66 rue de la chaussee d'Antin - 75009 PARIS",
    "version": "1.0",
    "sellers": [
        {

The seller object contains each seller with the following information, among others:

• seller_id - the seller’s Id; in case of Equativ’s sellers.json file, this is the network Id; this Id is identical to the Field #2 (“Publisher’s Account ID”) in the ads.txt file and in the SupplyChain.nodes array sid property; in most cases, it will also appear in the Publisher.Id property of an OpenRTB request
• name - the name of the company which is paid for inventory that is transacted under the given seller_id
• domain - the business domain name of the company which is paid for inventory that is transacted under the given seller_id
• seller_type - the seller type reflecting the level of directness:
  • PUBLISHER indicates that the inventory is on a site/app which is owned and operated by the seller
  • INTERMEDIARY indicates that the inventory is on a site/app which is not owned, but operated (resold) by the seller; note that in case of an INTERMEDIARY seller, the sellers.json file does not say on which website (publisher) the inventory sold by the intermediary is located; to determine this, a buyer must crawl the ads.txt file of a publisher (hosted at the root level of the publisher’s site) and compare the “Publisher’s Account ID” (Field #2 in the ads.txt file) with the seller_id in the sellers.json file. If both Ids are identical, the buyer knows that the seller is selling inventory of this publisher 
  • BOTH indicates that some inventory is on a site/app which is owned and operated by the seller, while other inventory is on a site/app which is not owned and operated by the seller
• is_confidential - 0 indicates that the identity of the seller is not confidential; 1 indicates that it is confidential

For documentation on all items in the seller object, see “Sellers.json object: Seller” (page 7) in the IAB sellers.json specification.

Here is an example of a seller object (see Equativ’s own sellers.json file for a complete sellers.json file example):

{
            "seller_id": "1234",
            "name": "mypublisher",
            "domain": "mypublisher.com",
            "seller_type": "PUBLISHER",
            "is_confidential": 0
        },
        {

This example indicates that the seller mypublisher has the seller ID 1234 in the advertising system and owns the inventory they sell (the seller type is PUBLISHER).

SupplyChain Object

The SupplyChain Object allows buyers to see all parties who are selling or reselling a given ad opportunity. Each party that participates in the transacting of inventory is represented by a node in the SupplyChain Object.
Buyers can cross reference each node in the SupplyChain Object against the data in the sellers.json and ads.txt files and gain insights and information about who the sellers in the supply chain are.

A node has these properties, among others:

• asi - the advertising system identifier; the domain name of the advertising system, e. g. smartadserver.com); this id is identical to Field #1 (“Domain name of the advertising system”) in the ads.txt file
• sid - the seller ID; identifies the seller of the inventory; Equativ will update its node with the network ID listed in Equativ sellers.json, while premium sales houses, aggregators and ad network will populate the ID of their supply source listed in their sellers.json file;

For documentation on all attributes in a SupplyChainNode, see this chapter on Github.

Sample of a bid request “BidRequest1” with a single node; the seller is “directseller.com”:
 

"bidrequest" : {
  "id": "BidRequest1",
  "app": {
    "publisher": {
      "id": "00001"
    }
  }
  "source": {
    "ext": {
      "schain": {
        "ver":"1.0",
        "complete": 1,
        "nodes": [
          {
            "asi":"directseller.com",
            "sid":"00001",
            "rid":"BidRequest1",
            "hp":1
          }
        ]     
      } 
    }
  }
}

Sample of a bid request “BidRequest1” being resold as BidRequest2; the seller is “reseller.com”:

"bidrequest" : {
  "id": "BidRequest2",
  "app": {
    "publisher": {
      "id": "aaaaa"
    }
  }
  "source": {
    "ext": {
      "schain": {
        "ver":"1.0",
        "complete": 1,
        "nodes": [
          {
            "asi":"directseller.com",
            "sid":"00001"
            "rid":"BidRequest1",
            "hp":1
          },
          {
            "asi":"reseller.com",
            "sid":"aaaaa",
            "rid":"BidRequest2",
            "hp":1
          }
        ]     
      } 
    }
  }
}

In the example above, note the 2 nodes: the first one is a copy from the originating bid request; the second node is the node of the reseller.

What premium sales houses, aggregators and ad networks need to do

It is strongly recommended to comply with the sellers.json and SupplyChain Object standards because many buyers are enforcing these  IAB quality specifications. Not complying with these standards can result in revenue losses on the supply side.

Host a sellers.json file

If you are a premium sales house, aggregator, ad network or any other organisation selling inventory on sites/apps you do not own, you must create a sellers.json file and host it at the root level of your website. Follow the instructions in chapter “Sellers.json” above as well as the sellers.json IAB specification.

Append SupplyChainNode in ad calls

If you are a premium sales house, aggregator, ad network or any other organisation selling inventory on sites/apps you do not own, you must append your SupplyChainNode to your ad calls to Equativ. Equativ will then add your node to the SupplyChain Object and send it in bid requests - along with Equativ’s own node.
The attributes of the SupplyChainNode must be appended in the following format: ver,complete!asi,sid,hp,rid,name,domain,ext
Read here for a detailed description of each attribute. Read SupplyChain for Non-OpenRTB Requests on Github for further examples of the SupplyChainNode format.
 

Append SupplyChainNode in Standalone ad calls (GET)

The example below shows a Standalone ad call with the schain parameter and the SupplyChainNode added manually: 

<script type="application/javascript" src="https://ced.sascdn.com/tag/1234/smart.js" async></script> <div id="sas_26374"></div> <script type="application/javascript"> var sas=sas || {}

;
sas.cmd=sas.cmd || [];
sas.cmd.push( function () {
    sas.call( {
        siteId: 364850, pageId: 1728405, formatId: 26374, tagId: "sas_26374", schain: "1.0,1!exchange1.com,1234,1,publisher,publisher.com"
    }
    , {
        networkId: 1234, domain: "https://www15.smartadserver.com"/*, onNoad: function() {} */
    }
    );
}

);
</script>

Append SupplyChainNode in OneCall ad calls (POST)

The example below shows a OneCall ad call with the schain parameter and the SupplyChainNode added manually:

<script src="//ced.sascdn.com/tag/620/smart.js" async></script>
<script>
   var sas = sas || {};
   sas.cmd = sas.cmd || [];
   sas.cmd.push(function() {
       sas.setup({ networkid: 620, domain: "//[subdomain].smartadserver.com", async: true });
   });
   sas.cmd.push(function() {
       sas.call("onecall", {
          siteId: 103409,
          pageId: 659846,
          formats: [
                 {id: 14968}
                ,{id: 14309}
                ,{id: 17669}
          ],
          target: '',
          schain: '1.0,1!exchange1.com,1234,1,publisher,publisher.com'
          });
       });
</script>

Append SupplyChainNode in case of Managed Holistic+
In case of Managed Holistic+, a SupplyChainNode is appended using the "Supply Chain Setup" section in the Managed Holistic+ UI. Read chapter "Setup in UI - sites" in the Managed Holistic+ article for more details.

Append SupplyChainNode in case of instream video integrations
To learn more about appending a SupplyChainNode in case of Equativ's proprietary Video plugin / Embedded Ad Manager integrations, read the documentation of the schain parameter in the Publisher settings of Equativ's video plugin documentation.

Append SupplyChainNode in case of Ad API integrations
To learn more about appending a SupplyChainNode in case of server side applications using Equativ's Ad API, read the documentation of the schain parameter in the POST - Ad API / Ad API - GET method articles.

Append SupplyChainNode in case of standalone VAST request integrations
In case of standalone VAST request integrations (see section "Standalone VAST request" here), the SupplyChainNode is appended using the schain parameter (more about the parameter in section "General parameters" in Ad API - GET method).
The following standalone VAST request contains the schain parameter:
Append SupplyChainNode in case of Equativ's Server Side Bidding integration
Similar to appending the SupplyChainNode to ad calls, ad networks must include the schain attribute in the bid request that is sent to Equativ's Server side bidding endpoint.

What direct publishers need to do

If you are using Equativ as a direct publisher, you own the sites/apps on which you monetize the inventory. In this case, there is no need for you to host a sellers.json file nor append a SupplyChainNode. However, it is strongly recommended to create and host an ads.txt file. Read the dedicated ads.txt article for more details.