Guide to Setting Up Deals With API V1

Vaida
Vaida
  • Updated

Important

We've released Seller Deals v2 API, which supports Google DV360 Buyer IDs and the latest DV360 deal synchronization workflow. As a result, we're deprecating Seller Deals v1 API, with the removal date set for May 1, 2027. Please review and follow the Seller Deals v2 —Migration Guide to migrate to the new API version before the removal date.

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 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 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

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

Seller Buyers API

agencyId

Specify the agencies within Adform DSP to target in the deal

Seller Buyers API

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 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

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.

Important

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

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.

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

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.

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.

Important

You can add agency IDs only if you've included Adform DSP as a demand partner in demandPartnerIds.

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.

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

Seller Deals

Seller Buyers

Seller Buyers

Placements

Placements

Was this article helpful?

/
How can we make it better?

Thank you for your feedback!