Guide to Setting Up Deals With API V2

Solveiga
Solveiga
  • Updated

A deal is an agreement between a publisher and an advertiser to sell a publisher's inventory for a negotiated price through programmatic advertising. 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.

Tip

For more information about deals, see Learn About Deals in Adform SSP.

After you've created a publisher, placements, and creative settings, you can create deals to start selling your inventory.

With Seller Deals v2 API, you can create preferred, private auction, and programmatic guaranteed deals. You can also update the settings of each deal and retrieve deal details.

Authentication

To authenticate and use Adform APIs, your user account must have the necessary permissions and your OAuth client must have the required scopes assigned to it.

To create a deal, Adform SSP user account must have these permissions assigned by the business account admin:

  • Manage Deals

  • View Publishers & Placements

Depending on your objectives and workflow, you'll need some or all of the following scopes assigned to your OAuth client by Adform Support (technical@adform.com):

  • https://api.adform.com/scope/seller.deals: Grants access to Seller Deals V2 API.

  • https://api.adform.com/scope/api.placements.read: Grants access to Placements API.

  • https://api.adform.com/scope/seller.buyers: Grants access to Seller Buyers API.

  • https://api.adform.com/scope/dmp.dataproviders.readonly: Grants access to DataProvider section of the Data Management Platform API. This is needed only if you have a DMP account linked to your SSP account and you want to target specific audiences with your deals.

  • https://api.adform.com/scope/dmp.categories.readonly: Grants access to Category section of the Data Management Platform API. This is needed only if you have a DMP account linked to your SSP account and you want to target specific audiences with your deals.

  • http://api.adform.com/scope/dmp.segments.readonly: Grants access to Segment section of the Data Management Platform API. This is needed only if you have a DMP account linked to your SSP account and you want to target specific audiences with your deals.

Tip

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

Prerequisites

To set up a deal with API, you must use the following IDs in your requests:

ID

Used To

Retrieve From

placementId

Specify the placement for which the deal is set up

Placements API

creativeSettingsId

Specify the creative settings assigned to the placement

Important

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

Placements API

demandPartnerId

Specify the DSPs to target in the deal

Note

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

For Google DV360 deals, Google's demand partner ID is 3.

Seller Buyers API

buyerId

Specify the buyers to target in the deal

If the demand partner is Adform, use the agency's ID. If the demand partner is Google DV360, use the buyer's ID with Google DV360.

Note

Buyer ID represents the buyer's Partner ID with Google.

If the demand partner is Adform, to get the agency's ID, use the Seller Buyers API.

If the demand partner is Google DV360, to get the buyer's ID, contact the buyer.

Note

Some DV360 buyers use multiple Partner IDs. Confirm with your buyer which ID you should use for deal delivery and reporting, and use that ID.

dataProviderId

Specify the DMP data provider to use for deal targeting

Use only if you have a DMP account linked to your SSP account and you want to target specific audiences with your deals

Note

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

DataProvider section in Data Management Platform API

categoryId

Specify the DMP category to use for deal targeting

Use only if you have a DMP account linked to your SSP account and you want to target specific audiences with your deals

Category section in Data Management Platform API

segmentId

Specify the DMP audience to use for deal targeting

Use only if you have a DMP account linked to your SSP account and you want to target specific audiences with your deals

Segment section in Data Management Platform API

Note

Additional IDs might be used, but the listed ones are required to pass a request.

Deal Creation Workflow

After you've created a placement and assigned creative settings to it, you can continue with creating a deal.

To create a deal using Seller Deals API, you need to complete these steps:

  1. Create a deal.

  2. Update the deal.

1. Create a Deal

To create a new deal, use the POST endpoint in the Seller Deals V2 API. Depending on the deal type that you want to create, you need to set up specific deal settings for priority, price, and buyers.

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

demandPartners and buyerIds (specified under buyers)

  • To target all demand partners and buyers, set allDemandPartners and allBuyers values to true.

  • To target Adform as the demand partner, set allDemandPartners to false and set the demandPartnerId value to 1.

    • To target all buyers, set the allBuyers value to true.

    • To target specific buyers, set the allBuyers value to false and provide buyerIds for the agencies you want to target.

  • To target GoogleDV360 as the demand partner, set the allDemandPartners value to false and the demandPartnerId value to 3.

    • Set the allBuyers value to false and provide the buyer ID in the buyerIds value.

    Note

    Buyer ID represents the buyer's Partner ID with Google. Enter a positive number up to 19 digits. You can use only one buyer ID per deal.

    Some DV360 buyers use multiple Partner IDs. Confirm with your buyer which ID you should use for deal delivery and reporting, and use that ID.

  • To target other 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.

    Note

    If your deal targets selected demand partners that don't include Adform or Google DV360, you can't target specific buyers. In such case, set the allBuyers value to false and leave the buyerIds value empty.

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

Important

Currently, Adform DSP is the only demand partner supported for programmatic guaranteed deals.

To target all buyers in Adform, set the allBuyers value to true and leave buyerIds value empty.

To target selected buyers in Adform, set the allBuyers value to false and include the IDs of buyers that have access to your deal in the buyerIds value.

See the parameter list for more information about the required and optional parameters.

Note

For more information about Google DV360 deals, see Google DV360 Requirements.

Tip

To learn how to use Adform APIs, read the Guide to Using Adform APIs.

2. Update a Deal

Seller Deals API provides separate endpoints to update:

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, use the PUT endpoint in the Seller Deals API.

Note

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

See the parameter list for more information about the required and optional parameters.

List of Seller Deals API Parameters

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

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.

Important

For deals with Google DV360, leave the dealId value empty, as GoogleDV360 supports only automatically generated deal IDs.

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.

    Note

    For deals with Google DV360, use the fixed price type.

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

fixed, auction

String

allDemandPartners

Required

allDemandPartners is specified under buyers.

This parameter defines whether all demand partners can buy inventory through the deal. If set to true, all demand partners are included. If set to false, the specific demand partner IDs must be listed.

false

Boolean

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, leave the demandPartnersIds value empty.

1

Integer

allBuyers

Required

allBuyers is specified under buyers.

This parameter defines whether all buyers belonging to Adform DSP can buy the inventory sold through the deal. If set to true, all buyers are included. If set to false, the specific buyer IDs must be listed.

Note

When working with Google DV360 as the demand partner, set the allBuyers value to false and provide the specific buyer ID.

false

Boolean

buyerIds

Optional

buyerIDs is specified under buyers.

This parameter defines which buyers that belong to specific demand partners can buy the inventory sold through the deal.

If the demand partner is Adform, buyer IDs are agency IDs.

If the demand partner is Google DV360, buyer ID is the buyer's Partner ID with Google.

List buyer IDs if allBuyers value is false. If allBuyers value is true, leave the buyerIds value empty.

22

String

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.

Note

Only accepted deals will be available for buyers in Adform DSP.

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 dimensions of ad templates assigned to placements.

Note

Use this parameter to limit the placement creative settings available through the deal, not to extend the list of creative settings assigned to specific 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 specific audiences 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

Endpoints

Seller Deals v2

Seller Deals v2

Seller Buyers

Seller Buyers

Placements

Placements

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!