Create and Manage Deals With API

Vaida
Vaida
  • Updated

A deal is an agreement between a publisher and an advertiser to sell a publisher's inventory for a negotiated price by programmatic advertising. Publishers can make premium inventory available to selected advertisers through private marketplaces or deals within a subset of programmatic trading. With deals, publishers can increase their effective CPMs (eCPMs) and fill rates by offering a more specific inventory with first-party data privately.

Publishers can create deals that meet specific buyer needs. These deals can include selected or exclusive inventory, specific audience targeting, formats, or pricing. Publishers can also set up public deals that are available to any buyer that uses Adform DSP or external DSP partners.

Deals can be standard or programmatic guaranteed. Standard deals have two types — preferred (fixed price) deals and private auction deals. Here's how each type of deal differs:

  • Private Auction: A publisher can invite advertisers for exclusive bidding on special, non-guaranteed inventory packages before making them available in an open auction. All invited advertisers participate in an auction, which is won by the highest bidder. Adform considers the deal price as a floor price. The advertiser will pay the highest price they offer.

    This type of deal is beneficial when the publisher wants to:

    • Have more control over which buyers can bid on their inventory.

    • Get the highest CPM offer for their premium inventory.

    • Increase brand safety and avoid potential ad fraud.

  • Preferred Deal (Fixed Price): A publisher negotiates price and terms for exclusive inventory with a single advertiser for a first-look. There's no guaranteed buying or traffic reservation, but the publisher might want to negotiate a minimum spend. The deal price is fixed and the advertiser pays only the agreed CPM.

    This type of deal is beneficial when the publisher wants to:

    • Foster long-term partnerships with specific advertisers.

    • Negotiate higher CPMs for their premium inventory.

    • Maintain greater control over the brands and ads that appear on their platforms.

  • Programmatic Guaranteed (PG): A publisher and an advertiser directly negotiate a price and terms for the inventory that is reserved (guaranteed). Both publisher and advertiser commit to guaranteed traffic and spend. In Adform SSP, those deals represent the highest priority deal type for fixed-price trading within Adform exchange.

    This type of deal is beneficial when the publisher wants to:

    • Offer exclusivity to selected advertisers.

    • Guarantee revenue stream (due to fixed pricing).

    • Simplify the media buying process by reducing the need for constant monitoring and bid management associated with real-time bidding (RTB).

With Deals API, publishers can set up each of those deal types.

1642fbcb993fa3.png

Use Cases

Use Deals API to:

  • Optimize deal-related tasks, improve scalability, and save time with bulk actions for creating and retrieving multiple deals.

  • Simplify your workflows and improve efficiency by using Deals API to manage all your deals from your own system.

  • Create always-on deals based on performance KPIs or dynamic criteria, and to simplify the process of updating placements within deals.

Prerequisites

To start working with Deals API, you must:

Required Access

To work with Deals API, Adform must assign the following scopes to your OAuth client:

If you have a DMP account linked to your SSP account and you want to target it in your deals, you need additional scopes:

To get the required access, contact Adform Support (technical@adform.com) with your OAuth client and the list of needed scopes.

If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials for Adform APIs to register one.

Retrieve Necessary IDs

Before you can create or update deals using Deals API, you need to retrieve the following IDs to use in your requests:

Placement IDs (including creative settings IDs)

To use placements in your deals, you must create them in Adform platform. Once your placements are ready, you can retrieve their IDs using Placements API.

To retrieve placement IDs:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v1/seller/placements.

  5. Click Send.

If your placements have creative settings assigned to them, the provided API call returns both the placement IDs and their creative settings IDs.

Demand partner IDs

Demand partners are DSPs that you can target with your deal. To target specific demand partners, you must provide demand partner IDs when creating a deal. You can retrieve these IDs using Seller Buyers API.

To retrieve demand partner IDs:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/buyers/demandpartners.

  5. Click Send.

Note

Adform is the only demand partner supported for programmatic guaranteed deals. The ID of Adform's DSP is 1.

Agency IDs

Agencies are the advertisers within Adform DSP that you can target with your deal. To target specific agencies, you must provide agency IDs when creating a deal. You can retrieve these IDs using Seller Buyers API.

To retrieve agency IDs:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/buyers/agencies.

  5. Click Send.

DMP IDs (data provider ID, category IDs, segment IDs) (optional)

If you have a DMP account linked to your SSP account, you can target the audiences in that DMP. To set up DMP targeting via Deals API, you must retrieve the data provider ID as well as any category IDs and segment IDs that you want to use. Adform has different DMP APIs that you can use to retrieve the necessary IDs.

To retrieve the data provider ID:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v1/dmp/dataproviders.

  5. Click Send.

To retrieve category IDs:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v1/dmp/categories.

  5. Click Send.

To retrieve segment IDs:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v1/dmp/segments.

  5. Click Send.

Note

To link a DMP account with an SSP account, reach out to Publishers Support (publishers@adform.com).

Create a Deal

To create a new deal, set up your API request body in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select POST method.

  4. In the request URL field, enter https://api.adform.com/v1/seller/deals.

  5. Copy the example request body provided under POST method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your deal. See the parameter list and the request body model for more information.

  8. Depending on the deal type that you want to create, set up specific deal settings for priority, price, and buyers. See the table below for more information.

To create a private auction, preferred, or programmatic guaranteed deal, set up your deal settings as shown:

Parameter Name

Values for Private Auction Deal

Values for Preferred Deal

Values for Programmatic Guaranteed Deal

dealPriorityType (specified under priority)

pricePriority

firstLook

programmaticGuaranteed

level (specified under priority)

null

1 to 9

null

value (specified under price)

Deal floor price

Fixed CPM price

Fixed CPM price

type (specified under price)

auction

fixed

fixed

allDemandPartners and demandPartnerIds (specified under buyers)

To target all demand partners, set the allDemandPartners value to true and the demandPartnerIds value to null.

To target selected demand partners, set the allDemandPartners value to false and include the IDs of demand partners that have access to your deal in the demandPartnerIds value.

To target all demand partners, set the allDemandPartners value to true and the demandPartnerIds value to null.

To target selected demand partners, set the allDemandPartners value to false and include the IDs of demand partners that have access to your deal in the demandPartnerIds value.

Set the allDemandPartners value to false and the demandPartnerIds value to 1.

allAgencies and agencyIds (specified under buyers)

Agency settings depend on the selection of demand partners:

  • If your deal targets all demand partners, you must also target all agencies.

    To target all agencies, set the allAgencies value to true and agencyIds value to null.

  • If your deal targets selected demand partners that include Adform, you can target all or selected agencies.

    To target all agencies, set the allAgencies value to true and agencyIds value to null.

    To target selected agencies, set the allAgencies value to false and include the IDs of agencies that have access to your deal in the agencyIds value.

  • If your deal targets selected demand partners that don't include Adform, you can't target any agencies.

    In such case, set the allAgencies value to false and agencyIds value to null.

Agency settings depend on the selection of demand partners:

  • If your deal targets all demand partners, you must also target all agencies.

    To target all agencies, set the allAgencies value to true and agencyIds value to null.

  • If your deal targets selected demand partners that include Adform, you can target all or selected agencies.

    To target all agencies, set the allAgencies value to true and agencyIds value must be null.

    To target selected agencies, set the allAgencies value to false and include the IDs of agencies that have access to your deal in the agencyIds value.

  • If your deal targets selected demand partners that don't include Adform, you can't target any agencies.

    In such case, set the allAgencies value to false and agencyIds value to null.

To target all agencies, set the allAgencies value to true and agencyIds value to null.

To target selected agencies, set the allAgencies value to false and include the IDs of agencies that have access to your deal in the agencyIds value.

Update a Deal

Deals API provides separate endpoints to update:

  • All deal details

  • Creative settings

  • Deal status

If you need to update the entire deal or a placement, you must use the endpoint for all deal details.

To update all deal details, set up your API request body in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select PUT method.

  4. In the request URL field, enter https://api.adform.com/v1/seller/deals/{dealid}.

    Note

    Replace the {dealid} part in the endpoint with the ID of the deal that you want to update.

  5. Copy the example request body provided within that PUT method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your deal. See the parameter list and the request body model for more information.

Note

If you've used Postman to create the deal that you want to update, you can go to the History tab in the sidebar to reuse the values from the previous API call. For more convenience when working with APIs, consider using Postman collections to save and organize your API calls.

List of Deals API Parameters

All deals must include general deal settings as well as information about fees, availability, placements, and targeting. These are the parameters that you must define for all types of deals:

General Deal Settings

Parameter Name

Scope

Description

Enum or example values

Type

dealId

Optional

Deal ID can be custom or automatically generated.

Requirements for custom deal ID:

  • Deal ID can't start with "DID-". Adform uses this pattern to automatically generate deal IDs.

  • Deal ID must be unique per publisher's account.

  • Deal ID must start with a letter (A–Z, a–z).

  • Deal ID can have only these characters: A–Z, a–z, 0–9, hyphen ( - ), and underscore ( _ ).

  • Deal ID can have max 100 characters and can't have spaces.

For Adform to generate a deal ID automatically, set the dealId value to null or leave it empty.

DID-0000-000000

String

name

Required

Name can contain a maximum of 255 characters including spaces.

Deal_PG_1

String

dealPriorityType

Required

dealPriorityType is specified under priority.

Deal priority type defines the way Adform ranks bids in auctions:

  • First Look: Adform gives priority to buyers who are buying with a deal ID.

  • Price Priority: Adform selects the winner according to the price.

  • Remnant: Adform gives priority to the open auction.

  • Programmatic Guaranteed: Adform selects the buyer who is buying with a specific deal ID.

firstLook, pricePriority, remnant, programmaticGuaranteed

String

level

Required

level is specified under priority.

Level defines the priority of a deal in relation to other deals. You must define the level only for firstLook and remnant priority types.

Priority level values range from 1 to 9, with 1 being lowest priority and 9 being highest priority.

For pricePriority and programmaticGuaranteed priority types, set the level value to null.

5

Integer

value

Required

value is specified under price.

Value defines the price of the deal. Depending on the deal price type, value can be fixed CPM or deal floor price.

Value must be a number between 0.01 and 999999999.99.

Adform uses the currency selected in your SSP account settings.

10

Number

type

Required

type is specified under price.

Type defines the price type of the deal:

  • Fixed price: Deal collects a fixed CPM for each generated impression.

  • Auction: Deal has a floor price and all submitted bids participate in an auction.

fixed, auction

String

demandPartnerIds

Optional

demandPartnerIds is specified under buyers.

Demand partner IDs define which demand partners can buy the inventory sold through the deal.

List demand partner IDs if allDemandPartners value is false. If allDemandPartners value is true, set the demandPartnersIds value to null.

11

Integer

allDemandPartners

Required

allDemandPartners is specified under buyers.

This parameter defines whether all demand partners can buy the inventory sold through the deal.

false

Boolean

agencyIds

Optional

agencyIds is specified under buyers.

Agency IDs define which agencies belonging to Adform DSP can buy the inventory sold through the deal.

List agency IDs if allAgencies value is false. If allAgencies value is true, set the agencyIds value to null.

22

Integer

allAgencies

Required

allAgencies is specified under buyers.

This parameter defines whether all agencies belonging to Adform DSP can buy the inventory sold through the deal.

false

Boolean

advertiserAccessRulesBypassed

Required

This parameter defines whether advertiser access rules set on the inventory should be bypassed.

false

Boolean

status

Required

Status defines the status of the deal:

  • Pending: Status applies to a recently created or modified deal.

  • Accepted: Status applies to a deal that's been accepted by the publisher.

  • Rejected: Status applies to a deal that's been rejected by the publisher.

When deal status is accepted, the status value can no longer be changed to pending or rejected. In such case, you can change the status value only if you update other deal parameters.

pending, accepted, rejected

String

Deal Custom Fees

Parameter Name

Scope

Description

Enum or example values

Type

type

Required

type is specified under fee.

Type defines the fee type of the deal:

  • Fixed CPM fee: A fixed amount of the bid is deducted as a fee.

  • Revenue share fee: A percentage of the bid is deducted as a fee.

fixedFeeCpm, revenueShare

String

value

Required

value is specified under fee.

Value defines the deal fee. For fixed CPM fee deals, value is the amount deducted from the bid. For revenue share fee deals, value is the percentage deducted from the bid.

For fixed CPM fee deals, value must be a number between 0.01 and 999999999.99. For revenue share fee deals, value must be a number between 0.001 and 100.

0.1

Number

overridePublisherFee

Required

overridePublisherFee is specified under fee.

This parameter defines whether the deal fee should override the publisher fee.

false

Boolean

Deal Availability

Parameter Name

Scope

Description

Enum or example values

Type

from

Required

from is specified under validPeriod.

from parameter defines the start date of the deal.

YYYY-MM-DD

String

to

Optional

to is specified under validPeriod.

to parameter defines the end date of the deal. If your deal has no end date, set the to value to null or leave it empty.

YYYY-MM-DD

String

type

Required

type is specified under estimatedImpressions.

Type defines the time period over which impressions are counted. If impression count isn't relevant for your deal, set the estimatedImpressions value to null.

daily, total

String

count

Required

count is specified under estimatedImpressions.

Count defines the number of estimated impressions during the time period provided in type. If impression count isn't relevant to your deal, set the estimatedImpressions value to null.

100

Integer

termsAndConditions

Optional

Terms and conditions define any additional information to be included in the deal. Terms and conditions can contain a maximum of 65,535 characters including spaces.

If no terms and conditions apply to the deal, set the termsAndConditions value to null.

String

Deal Placements

Parameter Name

Scope

Description

Enum or example values

Type

id

Required

id is specified under placements.

Placement IDs define which placements are available through the deal. Deals without placements can't be activated.

12

Integer

creativeSettings

Optional

creativeSettings is specified under placements.

Creative settings define the formats and sizes of ad templates assigned to the listed placements.

2

Integer

Inventory Targeting

Parameter Name

Scope

Description

Enum or example values

Type

dataProviderId

Required

dataProviderId is specified under targetingRules and dmp.

Data provider ID defines the DMP account that is linked to the SSP account.

If SSP account doesn't have a linked DMP account, set the dmp value to null.

101

Integer

categoryId

Required

categoryId is specified under targetingRules and dmp.

Category ID defines the categories of the linked DMP account that can be targeted. You can set a maximum of 10 DMP targeting rules on a deal.

If SSP account doesn't have a linked DMP account, set the dmp value to null.

1001

Integer

segments

Required

segments is specified under targetingRules and dmp.

Segments define the segments in the categories of the linked DMP account that can be targeted. You can set a maximum of 10 DMP targeting rules on a deal.

If SSP account doesn't have a linked DMP account, set the dmp value to null.

10001

Integer

matchAll

Required

matchAll is specified in two places under targetingRules: keyValuePairs and keywords.

This parameter defines whether all key-value pairs and all keywords must be included in the impression.

false

Boolean

matching

Required

matching is specified in two places under targetingRules: keyValuePairs and keywords.

Matching defines the matching type for key-value pairs and keywords.

is, isNot

String

key

Required

key is specified under targetingRules and keyValuePairs.

key parameter defines the key in the key-value pair targeting rule. You can set a maximum of 1,000 key-value pairs on a deal.

If no key-value pair targeting rules apply to the deal, set the keyValuePairs value to null.

sport

String

value

Required

value is specified under targetingRules and keyValuePairs.

value parameter defines the value in the key-value targeting rule. You can set a maximum of 1,000 key-value pairs on a deal.

If no key-value pair targeting rules apply to the deal, set the keyValuePairs value to null.

football

String

keywords

Required

keywords is specified under targetingRules and keywords.

Keywords parameter defines the keywords in the targeting rule. You can set a maximum of 1,000 keywords on a deal.

If no keyword targeting rules apply to the deal, set the keywords value to null.

FIFA

String

List of API Operations

effective CPMsreal-time bidding

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!