Proposal object

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

A proposal represents a negotiation between the buyer and seller that has at least one deal that is subject to this negotiation. The following is a JSON example of the proposal object properties. For deal properties, see Deals object.

{
    "ProposalId": 1234,
    "DisplayName": "Test Proposal",
    "RevisionNumber": 1,
    "LastActivatedRevisionNumber": 1,
    "Buyer": {
        "BuyerId": "1",
        "BuyerContact": {
            "Name": "Buyer123",
            "Email": "buyer@ttd.com",
            "Phone": "123456789"
        }
    },
    "Seller": {
        "SellerId": "Seller123",
        "SellerName": "Seller123",
        "SellerLogoUrl": "Seller123.jpg",
        "SellerContact": {
            "Name": "Seller123",
            "Email": "Seller123@seller.com",
            "Phone": "123456789"
        }
    },
    "AdditionalBuyers": [
        {
            "BuyerId": "6789"
        }
    ],
    "Deals": [], // For illustration purposes, no deal properties are included here. For details, see the Deal Object.
    "Notes": [
        {
            "NoteId": 651,
            "ProposalId": 1234,
            "RevisionNumber": 1,
            "CreateTime": "2021-08-19T18:53:18.05",
            "CreatedBy": "Seller",
            "Content": " The body of the note"
        }
    ],
    "CreatedBy": "Seller",
    "LastUpdatedBy": "Seller",
    "ProposalState": "Activated",
    "SellerAccepted": "true",
    "BuyerAccepted": "false",
    "CreatedTime": "2022-08-19T18:53:18.05",
    "UpdatedTime": "2022-08-20T23:01:41.05"
}

Proposal object properties

The following table details the Proposal object properties.

Property	Required in Request?	Data Type	Description
`ProposalId`	Required (update)	Integer	The unique ID of the proposal. This ID is generated after the proposal is created.
`DisplayName`	Required	String(256)	The name of the proposal. Be sure to create a descriptive name that helps distinguish this proposal from others or indicate its content.
`RevisionNumber`	Required (update)	Integer	The latest revision number of the proposal. Here's what you need to know about this property: Revision number 1 is set automatically when the proposal is created. This number is automatically incremented for each proposal update, acceptance, and rejection via the respective APIs. For details, see the What You Need to Know section in Easy Proposal Activation API. IMPORTANT: When updating, accepting, or rejecting the proposal, be sure to include the current revision number or the update will fail.
`LastActivatedRevisionNumber`	Optional	Integer	The last revision that was activated after both parties accepted the deal terms in the proposal. TIP: If the proposal has been renegotiated since activation, you can use the GET /proposal/history/{ProposalId}/{RevisionNumber} endpoint to query this revision number from the history and see what terms have been activated.
`Buyer`	Required	Object	The main buyer of the negotiated deals in the proposal. NOTE: There can be additional buyers in non-guaranteed proposals.
`Seller`	Required	Object	The seller of the negotiated deals in the proposal.
`AdditionalBuyers`	Optional	Object array	The list of additional buyer seats for the proposal. IMPORTANT: Only proposals with non-guaranteed deals can have additional buyers.
`Deals`	Required	Object array	A list of deals associated with the proposal. IMPORTANT: A proposal must have at least one deal. If there are multiple deals in a proposal, all deals must be of the same deal type.
`CreatedBy`	N/A, response only	String(enum)	The party who created this proposal: `Buyer` or `Seller`.
`LastUpdatedBy`	N/A, response only	String(enum)	The party who last updated this proposal: `Buyer` or `Seller`.
`ProposalState`	N/A, response only	String(enum)	The current state of the proposal. Possible values include the following: `Proposed`—the deals are being negotiated. `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.
`SellerAccepted`	N/A, response only	Boolean	If set to `true`, indicates that the seller has accepted the current proposal. For details, see Easy Proposal Activation API. If set to `false`, the seller has not accepted the current proposal, or both parties accepted the proposal.
`BuyerAccepted`	N/A, response only	Boolean	This property has been deprecated, its value always `false`.
`Notes`	N/A, response only	Object array	All communication related to the proposal and all its revisions. For details, see Notes object.
`CreateTime`	N/A, response only	DateTime	The date and time when the proposal was created.
`UpdateTime`	N/A, response only	DateTime	The date and time when the proposal was last updated.

Buyer object

The buyer represents the main party negotiating and buying deals attached to the proposal. Here's what you need to know about this object:

Guaranteed proposals can have only the main buyer.
Non-guaranteed proposals can have additional buyers.

The following table details the Buyer object properties.

Property	Required in Request?	Data Type	Description
`BuyerId`	Required	String(32)	The partner seat ID in The Trade Desk platform. To retrieve a list of seat IDs in The Trade Desk Platform, or if a partner has Default Seat Mapping enabled, use the GET /proposal/seats endpoint. IMPORTANT: You cannot change this ID after creating the proposal.
`BuyerContact`	Optional	Object	The buyer's contact information.

Seller object

The seller represents the party selling negotiated deals. The following table details the Seller object properties.

Property	Required in Request?	Data Type	Description
`SellerId`	Required	String(64)	The publisher's unique identifier. If the `PublisherIds` property in the Deals object is empty, this ID must be the `seller_id` from the `sellers.json` file. If not, make sure it corresponds with the proposal in the deal object. IMPORTANT: You cannot change this ID after the proposal is created.
`SellerName`	Required	String(128)	The name of the seller. IMPORTANT: You cannot change this name after the proposal is created.
`SellerLogoUrl`	Optional	String	The URL of the seller's, or publisher's logo in the PNG, JPG, or GIF format.
`SellerContact`	Optional	Object	The seller's contact information.

AdditionalBuyer object

For non-guaranteed deals, this list represents 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.

The following table details the AdditionalBuyers object properties.

Field	Required in Request?	Data Type	Description
`BuyerId`	Required	String(32)	The partner seat ID in The Trade Desk platform. To retrieve a list of seat IDs from the platform, or if a partner has Default Seat Mapping enabled, use the `GET /proposal/seats` endpoint.

Contact object

A party can provide their name, email, or phone number in the corresponding Contact object. The following table lists its properties.

Fields	Required in Request?	Data Type	Description
`Name`	Optional	String(256)	The contact's name.
`Email`	Optional	String(256)	The contact's email address.
`Phone`	Optional	String(32)	The contact's phone number.

Notes object

The note that the buyer and seller created to provide further detail or communication associated with the proposal.

NOTE: To add a note to an existing proposal revision, use the POST /proposal/notes endpoint.

The following table details the Note object properties.

Property	Required in Request?	Data Type	Description
`NoteId`	N/A, response only	Integer	The unique ID of the note that was generated on creation.
`ProposalId`	N/A, response only	Integer	The unique ID of the proposal to which the note was added.
`RevisionNumber`	N/A, response only	Integer	The proposal revision number to which the note was added.
`CreateTime`	N/A, response only	DateTime	The date and time when the note was added.
`CreatedBy`	N/A, response only	String(enum)	The party who created this note: `Buyer` or `Seller`.
`Content`	N/A, response only	String(4000)	The body of the note attached to the proposal.