POST /proposal/query

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

Retrieves a list of existing proposals and their revisions. Use this endpoint to poll for updates of multiple proposals.

TIP: To avoid slowdowns and ensure that your results are returned quickly, be sure to use pagination and filters.

Request example

To retrieve a list of possible sort fields, use the GET proposal/query/facets endpoint.

{
    "BuyerIdFilter": [
        "5168"
    ],
    "PageSize": 1,
    "PageStartIndex": 0
}

Request object properties

The following table lists the POST /proposal/query request object properties.

Property Required? Value Type Description
SortFields Required Object Array The fields by which to sort the returned data.
Here's what you need to know about this property:
  • Duplicate IDs are not allowed.
  • To retrieve a list of possible sort field IDs, use the GET proposal/query/facets endpoint.
  • Sorting will happen in the order the sort fields are specified in the list.
  • If not specified, empty, or null, the results are listed in ascending order and sorted by proposal IDs.
See also Sort Field properties.
PageSize Required Integer The size of the page requested. If there are fewer items on the current page than the PageSize, only those items will be returned.
  • A PageSize of null or above 50 is equivalent to sending a PageSize of 50.
  • A PageSize of 0 means zero elements (useful if you just want item counts). In this case, the PageStartIndex is ignored.
For example:
  • If there are 30 items, PageStartIndex is 0, and PageSize is 50, only the 30 existing items will be returned.
  • If there are 100 items, PageStartIndex is 50, and PageSize is 50, the last 50 elements will be returned.
PageStartIndex Required Integer The zero-based index into the set at which to start the requested page. If you want the first page, this should be 0. If, for example, you want a page starting at the 13th element, this should be 12.
If PageStartIndex is equal to or greater than the number of items matching your filters, no items will be returned.
  • To find out how many items there are, request the first page at your desired PageSize, and the result will tell you how many items in the set match your filters and the total number of items in the set.
  • To find out when you've received the last page, check if the sum of PageStartIndex + items returned is greater than or equal to items matching filters. If it is, this is the last page (or you've requested an index beyond the last page).
DealTypeFilter Required String The DealTypes by which to filter the result. Possible values include the following:
  • Guaranteed
  • PreferredPrivateAuction
  • PreferredDealTerms
CreatedAfterFilter Optional String
(date-time)		 The creation date to use for filtering the search results. Only proposals that were created on or after the specified date are returned.
BuyerIdFilter Optional String Array
(date-time)		 A list of buyer IDs by which to filter the search results.
SellerIdFilter Optional String Array
(date-time)		 A list of seller IDs by which to filter the search results.
ProposalStateFilter Optional String Array
(date-time)		 A list of proposals that contain only the specified proposal state.
Duplicate values are not allowed.
To retrieve a list of possible sort field IDs, use the GET proposal/query/facets endpoint.
UpdatedAfterFilter Optional String
(date-time)		 A list of proposals that were updated after the specified date.
SellerNameFilter Optional String Array A list of proposals that contain only the specified seller name.
This is a case-insensitive field.
DisplayNameFilter Optional String A list of proposals that contain only the specified display name.
This is a case-insensitive field.
ExternalDealIdFilter String array Optional The list of external deal IDs by which to filter results. Here's what you need to know:
  • Filtered results will include all proposals with deals that match at least one of the provided IDs.
  • Each returned proposal will contain all of its deals, even if their IDs were not listed in this filter.
  • The maximum number of IDs per array is 50.

Sort Field properties

The following table lists the SortFields object properties.

Property Required? Value Type Description
FieldId String required The ID of the field by which to sort.
Ascending boolean nullable Whether to sort this field in ascending order (true) or descending order (false). If not specified, this defaults to true.

Response example

A successful response to a POST /proposal/query request returns Proposal objects that match the request with a result and filtered count.

{
    "Result": [
        {
            "ProposalId": 1234,
            "DisplayName": "Test Proposal",
            "RevisionNumber": 3,
            "LastActivatedRevisionNumber": 2,
            "Buyer": {
                "BuyerId": "5168"
            },
            "Seller": {
                "SellerId": "Test",
                "SellerName": "Test Seller"
            },
            "Deals": [
                {
                    "DealId": 5367297813,
                    "DisplayName": "Test Deal",
                    "ExternalDealId": "4263497813",
                    "PublisherIds": [
                        "1234"
                    ],
                    "DealType": "Preferred",
                    "PreferredDealTerms": {
                        "RateType": "CPM",
                        "Rate": {
                            "Amount": 0.05,
                            "CurrencyCode": "USD"
                        }
                    },
                    "CreativeRestrictions": {
                        "CreativeFormat": "Display"
                    }
                }
            ],
            "Notes": [],
            "Originator": "Seller",
            "LastUpdatedBy": "Seller",
            "ProposalState": "Proposed",
            "SellerAccepted": "false",
            "BuyerAccepted": "false",
            "CreatedTime": "2021-08-19T18:53:18.05",
            "UpdatedTime": "2021-08-20T23:01:41.05"
        }
    ],
    "ResultCount": 1,
    "TotalFilteredCount": 1
}

Response object properties

The following table lists the POST /proposal/query response object properties.

Property Value Type Description
Result Object Array The proposal objects that match the request.
ResultCount Integer The number of objects returned in the result.
TotalFilteredCount Integer The total number of objects available that match the request filters. If not present, then this property is not supported by this interface.

Error codes and messages

The following table provides a list of common errors and their respective HTTP error codes.

HTTP Code Status Description
400 Bad Request The request had missing or invalid parameters.