Deal participants

As the selling party, you initiate a deal by sending proposals to prospective buying parties. Before drafting the deal terms, you must identify each participant by their Known Agent ID (KAID). For details, see Get started with the PDP API for selling parties. Whether you are creating a commitment or endeavor deal, you must define all participants such as the buying and selling party, and optionally, additional participants who can access but not manage the deal.

A primary participant represents the main party from the buy and sell side. You can also specify buying permissions—for example, making the deal available only to certain advertisers or agencies, or restricting access by advertiser category. You can set deals to be available to specific advertisers or agencies, and apply restrictions by advertiser category.

When you assign each primary party, you must include the following information:

The known agent ID of the party.
The name and email address of the primary contact. You can skip this step for the buying party contact.

IMPORTANT: The following sections show only how to add deal participants during creation. To send a successful request, you must define the deal type using either the commitmentTerms or endeavorTerms field, along with any other required terms. For details, see Draft deal terms.

Pick your selling party

The selling party represents the primary party that handles the deal communication between the buying party.

NOTE: In cases where the owner of the inventory and the seller of the inventory isn't the same entity, the selling party might not be the same as the owner of the deal.

Here's what you need to know about selecting a selling party.

If you are creating a single-publisher deal in contact with the buying party, use your KAID as the selling party.
If you are creating a single-seller deal containing one or more specific publishers' inventory, use the KAID of the seller as the selling party.
If you are creating a deal on behalf of multiple sellers and publishers, or cannot find a specific KAID, use your KAID as the selling party.

The following diagram shows how to select the selling party.

IMPORTANT: Later in the creation process, you must add each publisher ID in the inventory terms.

Pick your buying party

Depending on whether the buying party is an advertiser or agency, the deal might have restrictions on who can bid. A buying party is an agency or advertiser who is the recipient of the deal. They are a single contact with the authority to accept or reject the deal. When sending a deal, you declare the buying party and other buyers through the aadv, badv, and wseat fields.

Here's what you need to know about finding a buying party:

You can look up buying parties in the Provisioning API.
Searching by name can produce duplicate values. Check with your buying party to confirm their KAID.
If a buying party isn't appearing in the search query, they may have chosen to opt-out. In this case, contact your buying party to get their KAID.

TIP: If a buying party cannot find their KAID, ask them to follow the UI steps in the Knowledge Portal.

The following diagram shows how to select the buying party.

Buying permissions

Use the `buyingPermissions` object to control which advertisers and agencies can access a deal. The appropriate settings depend on whether the buying party is an agency or a single advertiser.

Selling to agencies

When the buying party is an agency, you have two options: - **Let the buying party control access**: Leave the `buyingPermissions` object empty. - **Control access yourself**: Set restrictions on deal access by advertiser, agency, or advertiser category. | Parent | Field | Description | | --- | --- | --- | | `buyingPermissions.categories` | `acat` / `bcat` | Allow or block advertisers by category using IAB content category IDs. | |`buyingPermissions.advertisers` | `aadv` / `badv` | Allow or block specific advertisers by KAID. Overrides all allowed advertisers under the agency. | | `buyingPermissions` | `wseat` | Restrict bids to all advertisers under a specific agency by providing the agency's KAID. | For details on these fields, see [BuyingPermissions object](/doc/DealApiObjectReference#buying-permissions).

Selling to advertisers

When the buying party is a single advertiser, only that advertiser may buy through the deal. You must set the `aadv` field (within the `buyingPermissions.advertisers` object) to the KAID of the advertiser. >**IMPORTANT:** Do not include `badv`, `wseat`, or any other buyer permission fields when selling to a single advertiser.

Add deal participants

When you first initate a deal, you start by adding your deal participants in the dealCreate mutation. Here's what you must have to add deal participants:

IMPORTANT: If you don't have access to managed deals, you must include your deal ID in the id field.

Your account ID assigned during onboarding.
The deal name and deal ID, if applicable.
The KAID of the buying and selling party.
The contact information of the selling party.

Flexible deal for an agency

The following example dealCreate mutation shows a portion of the required deal terms related to setting up a deal where the buying party has control over who can access it. Additional non-participant related terms are not included.

NOTE: To allow for flexiblity, the buyingPermission object is ommited in this example.

mutation {
  dealCreate(
    input: {
      accountId: "ACCOUNT_ID_PLACEHOLDER"
      name: "DEAL_NAME_PLACEHOLDER"
      displayName: "SELL_SIDE_UI_PLACEHOLDER"
      categoryTaxonomy: IAB_TECH_LAB_CONTENT_TAXONOMY_2_2
      sellingParty: {
        id: "SELLING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "Alex Smith"
          email: "alexsmith@example.com"
        }
      }
      buyingParty: {
        id: "BUYING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "John Smith"
          email: "johnsmith@example.com"
        }
      }
      terms: {
        # DEAL TERMS MUST GO HERE!
      }
      createdBy: {
        name: "Jane Doe"
        email: "janedoe@example.com"
      }
    }
  )
}

Exclusive deal with an agency

The following example dealCreate mutation shows a portion of the required deal terms related to setting up a deal with a single agency. Additional non-participant related terms are not included.

mutation {
  dealCreate(
    input: {
      accountId: "ACCOUNT_ID_PLACEHOLDER"
      name: "DEAL_NAME_PLACEHOLDER"
      displayName: "SELL_SIDE_UI_PLACEHOLDER"
      categoryTaxonomy: IAB_TECH_LAB_CONTENT_TAXONOMY_2_2
      sellingParty: {
        id: "SELLING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "Alex Smith"
          email: "alexsmith@example.com"
        }
      }
      buyingParty: {
        id: "BUYING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "John Smith"
          email: "johnsmith@example.com"
        }
      }
      buyingPermissions: {
        wseat: ["AGENCY_KAID_PLACEHOLDER"]
      }
      terms: {
        # DEAL TERMS MUST GO HERE!
      }
      createdBy: {
        name: "Jane Doe"
        email: "janedoe@example.com"
      }
    }
  )
}

Deal for an advertiser

The following example dealCreate mutation shows a portion of the required deal terms related to setting up a deal with a single advertiser. Additional non-participant related terms are not included.

mutation {
  dealCreate(
    input: {
      accountId: "ACCOUNT_ID_PLACEHOLDER"
      name: "DEAL_NAME_PLACEHOLDER"
      displayName: "SELL_SIDE_UI_PLACEHOLDER"
      categoryTaxonomy: IAB_TECH_LAB_CONTENT_TAXONOMY_2_2
      sellingParty: {
        id: "SELLING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "Alex Smith"
          email: "alexsmith@example.com"
        }
      }
      buyingParty: {
        id: "BUYING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "John Smith"
          email: "johnsmith@example.com"
        }
      }
      buyingPermissions: {
        advertisers: { 
          aadv: ["ALLOWED_ADVERTISER_ID_PLACEHOLDER"]
        }
      }
      terms: {
        # DEAL TERMS MUST GO HERE!
      }
      createdBy: {
        name: "Jane Doe"
        email: "janedoe@example.com"
      }
    }
  )
}

Deal with multiple parties

The following example dealCreate mutation shows a portion of the required deal terms related to setting up a deal with an agency and advertiser. Additional non-participant related terms are not included.

mutation {
  dealCreate(
    input: {
      accountId: "ACCOUNT_ID_PLACEHOLDER"
      name: "DEAL_NAME_PLACEHOLDER"
      displayName: "SELL_SIDE_UI_PLACEHOLDER"
      categoryTaxonomy: IAB_TECH_LAB_CONTENT_TAXONOMY_2_2
      sellingParty: {
        id: "SELLING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "Alex Smith"
          email: "alexsmith@example.com"
        }
      }
      buyingParty: {
        id: "BUYING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "John Smith"
          email: "johnsmith@example.com"
        }
      }
      buyingPermissions: {
        advertisers: { 
          aadv: ["ALLOWED_ADVERTISER_ID_PLACEHOLDER"]
          badv: ["BLOCKED_ADVERTISER_ID_PLACEHOLDER"]
        }
        categories: { 
          acat: ["644", "551"]
          bcat: ["360", "366"]
        }
        wseat: ["AGENCY_KAID_PLACEHOLDER"]
      }
      terms: {
        # DEAL TERMS MUST GO HERE!
      }
      createdBy: {
        name: "Jane Doe"
        email: "janedoe@example.com"
      }
    }
  )
}

Next steps

To fill out the terms object, see Draft deal terms.

FAQs

The following are commonly asked questions about deal participants.

Can a deal have more than one primary buying party or selling party?

No. There can only be one representative party from the buy-side and sell-side of the deal. The buying party is responsible for accepting the deal and can grant access to other buyers under their portfolio of buyer seats to access the deal, unless you use buyingPermissions object to restrict bidding permissions to specific known agent IDs in the advertisers or wseats field.

How do I view the parties of my deal?

You can query for the details of parties that you have had deals with in the past. For details, see Retrieve deal parties.

What do I do if I created a deal externally?

If you are sending a deal made outside of our platform, you must provide the deal ID in the id field to signfify that it's an external deal.

Who can I send deals to?

You can send deals to any buying party as long as you have their KAID.

Some parties may choose to opt out of having their KAID be queryable. In these cases, contact them directly and request for their ID. For details on UI instructions for the advertisers and agencies, see Finding your buying party ID in the Knowledge Portal.