Marketplace API

Overview

The Authorized Buyers Marketplace API is a collection of resources that buyers can use to programmatically manage the following:

• Negotiations with publishers
• Auction packages
• Client access to the Authorized Buyers Marketplace UI

This guide introduces the Marketplace API, and explains how Marketplace API resources map to Marketplace features in the Authorized Buyers UI.

Bidders and buyers

The Marketplace API is consistent with the structure of the Real-time Bidding API. Both APIs use bidders and buyers as root-level resources for bidder and buyer operations. You can use the same bidder and buyer names in resource paths for the Real-time Bidding and Marketplace APIs.

Note: Although bidders and buyers are root-level resources, you can't call them in the Marketplace API. Use the Real-time Bidding API to access bidders or buyers with your OAuth 2.0 credentials.

Clients and client users

You can use the Marketplace API to create and manage clients and client users, and to programmatically grant agencies or advertisers access to your Marketplace tab in the Authorized Buyers UI.

A Client represents a client, agency or advertiser associated with your Authorized Buyers account.

A ClientUser represents a specific individual that has UI access under a Client. Client users can't access the Marketplace API. Client users have limited access to your account's Marketplace tab. Client user permissions are determined by the role specified in their parent Client.

Other resources in the Marketplace API refer to clients by the name specified in the Clients resource.

To learn more about clients and client users in the Authorized Buyers Marketplace UI, see the following Help Center articles:

• Create and manage clients and client users.
• Types of client access permissions.

Media Planners

A media planner is an agency or other entity that independently negotiates deals with publishers, and allows one or more bidders to place bids on behalf of their finalized deals. These deals are either private auction or preferred deals, and you won't be able to view or interact with them until they are finalized–after which, they will appear in the bidders.finalizedDeals.list response.

To determine if a given finalized deal was negotiated by a media planner, you can check whether the deal's mediaPlanner field has been populated. Media planners set a list of DSP-specific seat IDs that are eligible to transact on the deal, which can be viewed with the eligibleSeatIds field. In Real-time Bidding bid requests, these seat IDs may appear in allowlists or blocklists set by the publisher, which will determine whether bids are filtered from the auction. They can appear in the following BidRequest fields:

• OpenRTB protocol
  • BidRequest.wseat
  • BidRequest.bseat
  • BidRequest.imp.pmp.deals.wseat
• Google RTB protocol
  • BidRequest.adslot.allowed_seat_ids
  • BidRequest.adslot.blocked_seat_ids
  • BidRequest.adslot.matching_ad_data.direct_deal.allowed_seat_ids

Auction packages

You can use the Marketplace API to subscribe and unsubscribe buyers and clients from auction packages, and to view the auction packages you're subscribed to.

An AuctionPackage is similar to a bundle of targeting for Marketplace inventory. For example, an auction package might target a collection of URLs and mobile application IDs that are relevant to a buyer's business interests.

You can't create new auction packages with the Marketplace API. You can use the Authorized Buyers Marketplace UI to create auction packages. The Marketplace API doesn't include specific targeting information associated with auction packages.

You can share auction packages with other buyers and clients, and can have auction packages created by Google or other buyers shared with you.

See Auction packages for more information.

Publisher profiles

You can use the Marketplace API to view profiles for publishers you can negotiate with.

A PublisherProfile represents a publisher in the Marketplace API. Other resources in the Marketplace API refer to publishers with the name specified in their PublisherProfile.

Publisher profiles have similar information to Publishers in the Discovery tab of the Authorized Buyers Marketplace UI.

See How to discover publishers for more information.

Proposals and deals

You can use the Marketplace API to negotiate deals with publishers. Here are some ways you can use the Marketplace API to manage deals:

• Send new proposals.
• Negotiate with publishers.
• Finalize deals.
• Serve finalized deals.
• Start renegotiation of finalized deals.

Proposals represent the latest negotiation status of one or more deals between a buyer or client and a publisher, and are similar to the Authorized Buyers Marketplace UI's Negotiations tab.

Deals represent the latest terms of a deal being negotiated under a given proposal, and are comparable to the Authorized Buyers Marketplace UI's list of deals labeled CURRENT NEGOTIATION for a given proposal.

Finalized deals represent deals that have completed the negotiation phase and are ready to serve. This includes deals that are already serving. Finalized deals are similar to the Authorized Buyers Marketplace UI's Deals tab.

Depending on the type of deal you're negotiating, behavior might differ between Marketplace API resources. For example, buyers can't initiate negotiations for all deal types. To learn more about the Marketplace API implementation for negotiations, see the following resources:

• buyers.proposals
• buyers.proposals.deals
• buyers.finalizedDeals

To learn more about negotiations in the Authorized Buyers Marketplace UI, see the following:

• Negotiate a deal.
• Request a proposal for publisher inventory.
• Manage your deals.