Deals object

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

The Deals object represents an inventory offered as part of the proposal with associated restrictions for creatives.

Here's what you need to know about the Deals object:

• A Proposal object must have at least one deal in the request.
• A deal can have only one deal term object (GuaranteedTerms, PreferredDealTerms, and PrivateAuctionTerms) which depends on the deal type.
• You can reuse the same external deal ID only if the previous proposal with the existing deal ID matches the following criteria:
  • The buyer or seller deleted the proposal.
  • The proposal has never been activated and is in the Rejected state.
  • A party removed the deal that had the existing external deal ID.
• If there are multiple deals in a proposal, all deals must be of the same deal type.
• Each deal must have a creative format restriction.
• After creating the proposal, you can change a preferred deal to private auction and vice versa.
• You cannot change a preferred or private auction deal to guarantee.

The following is a JSON example of the Deals object.

{
    "DealId": 4263497813,
    "DisplayName": "Test Deal",
    "ExternalDealId": "4263497813",
    "PublisherIds": [
        "1234"
    ],
    "StartTime": "2022-08-15T04:00:00",
    "EndTime": "2022-09-15T04:00:00",
    "DealType": "Guaranteed",
    "GuaranteedTerms": { // Only for guaranteed deals.
        "RateType": "CPM",
        "Rate": {
            "Amount": 0.5,
            "CurrencyCode": "USD"
        },
        "GuaranteedLooks": 1,
        "GuaranteedImpressions": 0.6
    },
    "DealTargetingInfo": {
        "FrequencyCaps": [
            {
                "FrequencyCap": 1,
                "ResetIntervalInMinutes": 10
            }
        ],
        "GeoTargeting": {
            "Included": [
                "1n7jkq1fce",
                "d1gugk2qn6"
            ],
            "Excluded": [
                "q5xb319t45", 
                "8t9awngqi4", 
                "x3s3q8xqaj" 
            ]
        },
        "Sites": {
            "Included": [
                "finance.yahoo.com"
            ],
            "Excluded": [
                "google.com"
            ]
        },
        "MobileApps": {
            "Included": [
                "384590449"
            ],
            "Excluded": [
                "com.company.appname"
            ]
        },
        "DeviceTypes": {
            "Included": [
                "Tablet",
                "Mobile"
            ],
            "Excluded": [
                "PC",
                "ConnectedTV"
            ]
        },
        "AdEnvironments": {
            "Included": [
                "App",
                "MobileWeb"
            ],
            "Excluded": [
                "Web"
            ]
        },
        "Categories": {
            "Included": [
                "IAB9-25",
                "IAB9-26",
                "IAB9-5"
            ],
            "Excluded": [
                "IAB9-30"
            ]
        }
    },
    "CreateTime": "2022-08-19T18:53:18.05",
    "UpdateTime": "2022-08-20T23:01:41.05"
}

Deal object properties

The following table details the Deal object properties.

GuaranteedTerms object

The GuaranteedTerms object represents the terms that are negotiated for a programmatic guaranteed deal. The following table lists its properties.

PreferredDealTerms object

The PreferredDealTerms object represents the terms that are negotiated for a preferred deal. The following table lists its properties.

PrivateAuctionTerms object

The PrivateAuctionTerms object represents the terms that are negotiated for a private auction deal. Here's what you need to know about this object:

• If you include RateType in the request, you must also include Rate.
• If you update RateType to null, you must also update Rate to null.

The following table details the PrivateAuctionTerms object properties.

Rate object

This object represents the monetary amount with its currency. The following table details the Rate object properties.

CreativeRestrictions object

The CreativeRestrictions object specifies the creative format restrictions that are supported by the publisher for this deal. The following table lists its properties.

CreativeSpecification object

The CreativeSpecification object specifies the list of creative attributes to which you want to apply restrictions. The following table lists the properties of this object and indicates the creative specification and the creative formats to which restrictions apply.

DealTargetingInfo object

The DealTargetingInfo object provides information for supply-side targeting that is associated with the deal. The following table lists its properties and the targeting criteria that you can include or exclude from the deal.

FrequencyCaps object

The FrequencyCaps object array is a list that is set up on the supply side and limits how often a single user can be served the same inventory. The following table lists its properties.

TargetingCriteria object

The TargetingCriteria object provides a list of what to include and exclude from targeting. The following table lists its properties.