Easy Proposal Activation API

NOTE: The EPA API has sunset on September 30, 2026. Endpoints are no longer accessible. For alternatives, see EPA to PDP Migration.

The Trade Desk Easy Proposal Activation (EPA) API, also known as Proposal API, enables a seller and buyer to create proposals and negotiate the terms of contract deals.

IMPORTANT: To access the Proposal API, be sure to request the appropriate role and credentials from your Account Manager.

REST calls

To manage production-release processes, we provide environments for users using REST to access the EPA API. To specify which production environment to make calls to, use the root URL in the following table.

API	Root URL
REST	`https://api.thetradedesk.com/v3/`

For details on generating authentication tokens, see API token authentication.

What you need to know

Here's what you need to know about proposals:

There are two parties, the buyer and seller, who negotiate, accept, and update the deal terms in the proposal.
After the buyer and seller accept the proposal the following occurs:
- The respective BuyerAccepted and SellerAccepted values are reset to false and the ProposalState value changes to Accepted.
- The Trade Desk activates the proposal, the ProposalState value changes to activated, and the agreed upon terms are used in bidding. See also Proposal negotiation workflow.
After a party updates or changes the proposal, the ProposalState value is set to Proposed.
A proposal must have at least one deal.
Each deal must specify a creative format restriction and an external deal ID from the bid request.
Multiple proposals may not have the same external deal ID.

Terms and definitions

The following table defines the key terms used by the API.

Term	Description
Buyer	A partner in The Trade Desk platform who negotiates, accepts, and bids on the deals associated with the proposal. Buyers are identified by their partner seat ID.
Additional Buyer	The list of additional buyer seats of other partners in The Trade Desk platform that the SSP allows to bid on the deals associated with the proposal. This enables the main buyer to create a delivery profile and give those partners access to bid on the deals associated with the proposal.
Seller	The publisher who is selling the negotiated deals. Publishers are identified by the seller ID from the `sellers.json` file or any unique ID from the seller SSP.
Deals	The terms of the proposal that are being negotiated. For details, see Deal types.
Revisions	A revised version that reflects significant updates and changes made to the proposal, including accepting and rejecting it. For details, see Revisions.
Proposal State	The current status of the proposal, which indicates if it has been accepted, rejected, activated, or is still being negotiated. For details, see Proposal states.
Notes	Additional comments on proposal updates and other communication exchanged between the buyer and seller during the proposal negotiation.
Renegotiation	An update made to an activated proposal during which the `ProposalState` value is set to `Proposed`. See also Proposal negotiation workflow.

Revisions

Revisions keep track of updates that were made to the proposal. Here's what you need to know about revisions:

The system automatically creates the first revision and assigns revision number 1 to it when you create a proposal.
For every proposal update and state change, a new revision is automatically created, and the revision number is incremented by 1.
Adding a note to a proposal does not create a new revision of that proposal.
When updating, accepting, or rejecting the proposal, be sure to include the current revision number or the update will fail. To get the current revision of a proposal, use the GET /proposal/{ProposalId} endpoint.
To indicate which terms are used in bidding, after the proposal is activated, its revision number is automatically set as the LastActivatedRevisionNumber value.

Deal types

The API supports three deal types.

Here's what you need to know about deal types.

All deals in a single proposal must have the same deal type.
If needed, after creating the proposal, you can change a preferred deal to private auction and vice versa, as long as all deals are of the same type after the change.
You cannot change a preferred or private auction deal to guaranteed.

The following table compares the different deal types.

Comparison aspect	Programmatic Guaranteed	Preferred	Private Auction
Inventory	Reserved, commitment	Unreserved, no commitment	Unreserved, no commitment
Price	Fixed only	Fixed or variable-floor	Fixed or variable-floor
Start and end dates	Required	Optional	Optional
Buyers	Single buyer only	Additional buyers are allowed	Additional buyers are allowed

Proposal states

The following table lists the possible states of a proposal.

Proposal State	Description
Proposed	A party updated or created the proposal to negotiate the new deal terms.
Accepted	The proposal was accepted by both the seller and buyer.
Activated	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.
Rejected	The negotiated deals were rejected by either the seller or buyer.

Proposal creation, negotiation, and management tasks

When working with the Proposal API, you can perform a variety of tasks, such as submitting, negotiating, renegotiating proposals, looking up their revisions, and more.

The following table lists all tasks relating to working with proposals and the corresponding endpoints.

Task	Endpoint	Creates New Revisions?	Proposal State	Notes
Create a proposal.	POST /proposal	Creates the first revision.	Proposed	Use this endpoint and include the required proposal and deal information in the request.
Update a proposal.	PUT /proposal	Creates a new revision.	Proposed	Use this endpoint and include the required proposal and deal information in the request. IMPORTANT: Be sure to include the latest revision number of the version that you want to update.
Accept a proposal.	POST /proposal/accept	Creates a new revision.	Accepted Activated	Both the seller and buyer must accept the proposal. The seller must accept it first. After both parties accept the proposal, it is ready to be activated by The Trade Desk.
Retrieve a specific revision of a proposal.	GET /proposal/history/{ProposalId}/{RevisionNumber}	N/A	N/A	N/A
Add a note to a proposal revision.	POST /proposal/notes	Does not create a new revision.	No Change	N/A
Reject a proposal.	POST /proposal/reject	Creates a new revision.	Rejected	If a party rejects a proposal that has not been activated, neither party can update or accept the proposal. If a party rejects a proposal that has been activated, only the current deal terms are rejected. The seller can still update the proposal and both parties can still accept it.
Retrieve a list of seat IDs.	GET /proposal/seats	N/A	N/A	Use this endpoint to identify the buyer in The Trade Desk platform.
Retrieve a list proposal facets.	GET /proposal/query/facets	N/A	N/A	Use this endpoint to provide a list of possible sort fields that you can use in a POST /proposal/query request.
Retrieve a filtered list of proposal revisions.	POST /proposal/query	N/A	N/A	Use this endpoint to retrieve a list of changes that were made to proposals within a specific time period. To get a list of possible sort fields, use the GET proposal/query/facets endpoint.
Retrieve the current revision of a specified proposal.	GET /proposal/{ProposalId}	N/A	N/A	N/A
Delete a proposal.	DELETE /proposal/{proposalId}	N/A	N/A	Delete the proposal and all associated revisions.

Proposal negotiation workflow

The following diagram illustrates the proposal negotiation process between the seller SSP and the buyer on The Trade Desk platform.

FAQs

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

How do I activate a proposal?

The Trade Desk activates proposals after the seller and buyer accept the proposal. The terms specified in the proposal revision that was activated are used in bidding.

What happens if I update an activated proposal?

The current revision will continue to receive avails and bidding until The Trade Desk activates the new terms that both parties accept.

Can I change the seller or buyer?

No. After a proposal is created, you may not change any IDs, the buyer name, or the seller name. If you do, the request will fail.

Can additional buyers accept a proposal?

No. Each proposal is unique to a single buyer in The Trade Desk platform.

Can I add a buyer to a proposal?

Only proposals with non-guaranteed deals can have additional buyers.

Can a proposal have multiple sellers?

No. Each proposal is unique to a single seller.

Can a proposal have multiple deals?

Yes, as long as all deals are of the same type.

How do I identify which proposals were changed?

To identify which proposals were changed, use the POST /proposal/query endpoint and set the UpdatedAfterFilter value to the date of when you think the changes may have occurred.

How do I find out which revision was activated?

If a proposal was activated, use the GET /proposal/{ProposalId} endpoint to retrieve the current proposal revision with the last activated revision number in the proposal object.

How do I find the terms of a previous revision?

To retrieve the terms of a specific revision, use the GET/proposal/history/{ProposalId}/{RevisionNumber} endpoint and include the last activated revision number.

How do I retrieve geo targeting IDs for a deal?

To get a list of supported geo segment IDs, use the POST /v3/geosegment/query/supplyvendor endpoint.