EPA to PDP migration

With the release of the Price Discovery and Provisioning (PDP) API, deal participants can migrate from our legacy Easy Proposal Activation (EPA) API to the PDP API to manage the deal life cycle. The PDP API includes additional features that improve the transparency, performance, and efficiency of deals.

This document outlines the key changes to deal proposals, EPA REST API requests mapped to GraphQL mutations, and FAQs. To learn more about PDP, see Price Discovery and Provisioning overview.

NOTE: Depending on your version of the PDP API, standard deals are also known as endeavor deals, and use the endeavor deal type.

What's new

These changes range from deals to account identity. To access the PDP API endpoints, you need the account ID assigned during account onboarding.

The following table lists out the features in the PDP API and links to documentation to assist with migration.

Area Description Documentation
Get Started The migration from EPA to PDP changes the initial requirements for authentication, proposals, and identity. Getting started changes
Types Deals have different required deal types to distinguish between standard, commitment, and programmatic guaranteed (PG) deals, instead of preferred, private auction, and programmatic guaranteed (PG). Deal types
Statuses The proposal state expands to consider bidding activity and negotiation separately as deal statuses. Deal status
Inventory terms Deals have expanded support for category, supply, media, device, and many more terms.
NOTE: Categories support both IAB Content Taxonomy version 1.0 and version 2.2.		 Deal inventory terms
Endpoints The EPA REST endpoints map to equivalent operations in GraphQL that use either the PDP API or Platform API. Endpoint migration

Getting started changes

The following table describes the workflow changes for getting started with the PDP API, compared to the EPA API.

Area Description Documentation
Authentication PDP API authentication uses an API token specific to PDP. Authentication
Proposals Deals represent all EPA proposals. Proposals that contain multiple deals are a single deal.
NOTE: Previously inactive proposals have the PAUSED status.		 Proposal
Identity To provide a better system for identity management, known agent IDs (KAIDs) replace buyer seats. Identity

Authentication

The PDP API consists of endpoints used to manage deals and define relationships between buyers and inventory suppliers. Authentication uses an API token specific to PDP and the Deals endpoint and Provisioning endpoint.

For details, see Endpoint migration.

Proposal

Instead of EPA proposals, the PDP API focuses on improved proposal terms and activity tracking. These proposals, in the form of deals, require a known agent to identify each party and have many deal terms that can cover unique terms criteria not present in EPA. Only the selling party can create deals.

Identity

IMPORTANT: Use the known KAID to create a deal between deal participants.

Known agents are a concept introduced in the PDP API that replaces buyer seats. Known agents contain account identifiers that map the different types of deal participants. The selling party can use known agents to get the KAID and account name of their publishers and other buying parties. To view the known agent, you must have permission from the owner. For details, see Known Agent object.

Deal types

In the EPA API, deals types included preferred, private auction, or PG deals, but this applied additional restrictions during the deal life cycle. For instance, a PG deal could only send bids to fixed price auctions. With the PDP API, deals are now classified as standard, PG, or commitment, which offers flexibility toward assigning parameters and auction types. The type of deal chosen determines the different types of financial terms that apply.

The following table compares features for each deal type from EPA and PDP, in alphabetical order.

Deal Type API Auction Type Flight? Buyer Limit Inventory
Commitment PDP Fixed price, first price, or second price Required Multiple buyers Reserved, commitment
Endeavor PDP Fixed price, first price, or second price Required Multiple buyers Unreserved, no commitment
Preferred EPA Fixed price or variable floor Optional Multiple buyers Unreserved, no commitment
Private Auction EPA Fixed price or variable floor Optional Multiple buyers Unreserved, no commitment
Programmatic Guaranteed EPA and PDP Fixed price Required Single buyer Reserved, commitment

TIP: You can recreate EPA deals with the PDP API to access more capabilities. For details, see FAQs.

Deal status

In the EPA API, the proposal state values represent a combination of both buy side and sell side states. In the PDP, the proposal states have split up as deal negotiation status and deal spending status.

The following table lists all the statuses from the EPA API and how they've changed into negotiation statuses in the PDP API.

Enum Value Exists in PDP Description
PROPOSED Yes A deal proposal has been created by an inventory supplier and is waiting for a response from the buyer.
ACCEPTED Yes The proposal was accepted by both the seller and buyer.
REJECTED Yes The current revision of the deal has been rejected by the buyer. Previously accepted deal revisions can still be used.
ACTIVATED No The Trade Desk has activated the proposal after both parties accepted its terms. The seller can now receive bid requests that adhere to the deal terms of the proposal.

NOTE: Each EPA deal status related to proposal activation uses separate spending statuses in the PDP API.

The following table lists the deal spending status values in the PDP API. In the PDP API, this appears in the dealStatus field.

Enum Value Description
CANCELED The deal is canceled by either party before flight completion.
COMPLETED The accepted deal has reached the end of the flight date.
EXPIRED The deal was never accepted and the flight ended.
LIVE The deal has been accepted, is being targeted, and is live in flight.
LIVE_NOT_SPENDING The deal has been accepted by the buying party, but hasn't been targeted in any campaigns.
NOT_STARTED The deal has been accepted by the buying party, but flight dates haven't been reached.
PAUSED The deal has been paused by the selling party.
PENDING_ACCEPTANCE The deal has been proposed by a selling party and is waiting for a response from the buying party.

Deal inventory terms

IMPORTANT: New deals must include the corresponding IAB taxonomy version in the categoryTaxonomy field.

With the introduction of updated category options in version 2.2 of the IAB Tech Lab Content Taxonomy, PDP deals support both IAB version 1.0 and IAB Version 2.2 category IDs. For details on how version 1.0 maps to version 2.2, see IAB content taxonomy mapping: Version 1.0 to 2.2. Additionally, deals can specify optional information for the criteria in the following table:

The following table lists the inventory terms in PDP.

Criteria Description
Inventory channel You can choose from multiple inventory channels, including audio, video, display, DOOH, native audio, and native video.
Audience You can specify delivery characteristics such as device information, location, and ad environment.
Supply You can specify what premium inventory to sell or restrict. Filters include domain, network, applications, and more.
Sensitive content You can allow or block content categories, ratings, and inventory quality.

Signals

You can request to promise that deal participants send certain bidstream signals to improve metadata tracking and deal quality metrics. In order to calculate that the win rate is within the agreed minimum win rate threshold, The Trade Desk requires deal participants to send certain signals, such as SOURCE_TID.

NOTE: For a list of required signals in a commitment deal, see Bidding terms enumeration values.

Endpoint migration

As part of the migration, EPA endpoints transition to use either the Platform API or PDP API, based on whether the endpoints are on the buy side or sell side. The PDP API assists the selling party in deal proposal, negotiation, and management, while the Platform API enables the buying party to send requests to view and decide on deals.

Refer to the following sections for your API:

PDP API endpoints

IMPORTANT: To call the PDP API endpoints, you must complete the steps in PDP API authentication and select the Deals root URL or Provisioning root URL listed in Seller Sandbox.

The following table shows endpoints in the EPA API and their equivalents in the PDP API.

EPA Endpoint EPA Description PDP Equivalent Documentation
POST /proposal Creates a new proposal. dealCreate Initiate and negotiate deals.
PUT /proposal Updates an existing proposal and creates a new revision. dealRevise Revise a deal
POST /proposal/notes Submits a new note to an existing proposal. dealNoteCreate Deal notes
DELETE /proposal/{ProposalId} Deletes the specified proposal. dealRemove Remove a deal
POST /proposal/query Retrieves a list of existing proposals and their revisions. Includes updates of multiple proposals. deals Retrieve your deals
GET /proposal/{ProposalId} Retrieves the latest revision of the specified proposal with all related data such as deals and notes. deals
  • Retrieve commitment deal terms
  • Retrieve endeavor deal terms
GET /proposal/history/{ProposalId}/{RevisionNumber} Retrieves a revision of an existing proposal for the specified proposal ID and revision number. auditLog Retrieve deal revision history
GET /proposal/query/facets Retrieves a list of facets that you can use to look up proposals with the POST /proposal/query endpoint. N/A Deal search parameters
GET /proposal/seats Retrieves a list of default seats for buyers in The Trade Desk platform. knownAgents Known agents

Platform API endpoints

The following table shows endpoints in the EPA API and their equivalents in the Platform API. Replace the {dealType} placeholder with your deal type value of Commitment or Endeavor.

NOTE: PG deals are grouped under commitment deals and standard deals are grouped under endeavor deals.

EPA Endpoint EPA Description Platform Equivalent
POST /proposal/accept Accepts the current proposal revision. inventory{dealType}Accept
POST /proposal/reject Rejects the current proposal revision and returns a new revision in a rejected state. inventory{dealType}Reject
POST /proposal/notes Submits a new note to an existing proposal. inventory{dealType}NoteCreate
DELETE /proposal/{ProposalId} Deletes the specified proposal. inventory{dealType}BulkArchive

FAQs

The following is a list of commonly asked questions about the PDP API.

How do I recreate preferred and private auction deals in the PDP API?

To transfer preferred and private auction deals, follow these steps:

  1. Create a standard deal with an empty spend tier.
  2. Add deal flight information, with a start date to end date maximum duration of two years.
  3. Select a category taxonomy to use, even if you do not have any content terms.
  4. Provide agreed-upon bidstream signals. Standard deals do not have required signals imposed by The Trade Desk.

What is the Deal Quality Score (DQS)?

DQS is a metric used to improve deal transparency and accountability. The score takes into consideration various factors such as how well both parties keep to their agreements, and calculations such as the win rate, bidding signals, and targeting relevance. DQS is a strong metric to determine whether you should negotiate new terms to revise the existing deal.

Here's what you need to know about DQS: