Guide to Setting Up Deal Groups With API

Vaida
Vaida
  • Updated

A deal group is a collection of deals that share some criteria and can be assigned to programmatic and programmatic guaranteed line items as a unit. Such criteria can be a shared characteristic of the deals, such as a channel or a publisher, or a shared goal, such as a seasonal promotion or a brand awareness campaign.

Tip

For more information about deal group management, see Create Deal Groups.

Use deal groups to organize your accepted deals and put together the ones you plan to target across multiple line items.

With Deal Groups API, you can create, update, and retrieve deal groups. You can also retrieve lists of advertisers that are common to all specified deal groups, or all advertisers that appear in at least one of the specified deal groups.

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 set up a deal group, Adform DSP and Ad Server user account must have these permissions assigned by the business account admin:

  • Manage Programmatic Deals

  • Manage Programmatic Line Items

  • Manage Campaigns & Orders

  • View Advertisers (API Only)

Important

The user account must also have data access to the advertisers that you want to assign the deal groups to.

You also need the following scopes assigned to your OAuth client by Adform Support (technical@adform.com):

  • https://api.adform.com/scope/buyer.inventory.dealgroups: Grants access to Deal Groups API.

  • https://api.adform.com/scope/buyer.rtb.lineitem: Grants access to RTB Line Items Setup API.

  • https://api.adform.com/scope/buyer.marketplace.inventories.readonly: Grants access to Inventory Marketplace API.

  • https://api.adform.com/scope/buyer.advertisers.readonly: Grants read-only access to Advertisers Management API.

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 group with API, you must use the following IDs in your requests:

ID

Used To

Retrieve From

advertiserIds

Specify the advertisers that have access to the deal group

Advertisers Management API

inventorySourceId

Specify the inventory source of a deal

Inventory Marketplace API

dealId

Specify the deal to add to a deal group

Inventory Marketplace API

dealGroupId

Specify the deal group to update or assign to a line item

Provided as part of the response body after creating a deal group (see step 1 in Workflow)

Deal Group Creation Workflow

You can create deal groups to simplify deal assignment to your programmatic (RTB) line items.

To prepare a deal group to use in programmatic line items, you need to complete these steps:

  1. Create a deal group.

  2. (Optional) Update the created deal group.

  3. (Optional) Retrieve a list of deal groups to assign to line items.

  4. Assign deal groups to a line item.

1. Create a Deal Group

To create a deal group, use the POST endpoint in the Deal Groups API.

For more information about the required and optional parameters, see the parameter list.

Tip

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

The following are the limitations to keep in mind when creating a deal group:

  • A private deal group can have a maximum of 10 advertisers.

  • A deal group can have a maximum of 500 deals.

  • An account can have a maximum of 1,000 deal groups, including both active and inactive groups. Once you reach this number, you need to reuse your existing deal groups.

2. Update a Deal Group

Deal Groups API provides separate endpoints to:

Important

To update a deal group, you must have access to at least one advertiser assigned to the group.

To update all deal group details, use the PUT endpoint in the Deal Groups API.

Note

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

For more information about the required and optional parameters, see the parameter list.

3. Retrieve a List of Deal Groups

If you have multiple deal groups created, with Deal Groups API you can retrieve a complete or filtered list of your deal groups. Using data from your list, you can assign multiple deal groups to a line item.

To retrieve a list of deal groups, use the POST endpoint in the Deal Groups API.

For more information about the parameters you can filter by, see the parameter list.

4. Assign Deal Groups to a Line Item

You can assign deal groups to a programmatic line item that you have created. Before assigning a deal group, ensure that the deal group's status is active.

To assign deal groups to a line item, use the PUT endpoint in the LineItems section of the RTB Line Items Setup API.

Important

To assign a deal group to a line item, you must provide both the deal group ID and the IDs of all the deals within that group.

To unassign a deal group from a line item, you must remove both the deal group ID and all deal IDs that belong to that group.

You can remove the deal groups assigned to a programmatic line item using the same endpoint.

If you later edit a deal group (active or inactive) that is assigned to one or more line items, the changes will automatically be applied to the targeting setup of those line items.

List of Deal Groups API Parameters

These are the parameters that you must define when creating, updating, or retrieving a list of deal groups:

Deal Group Creation

Parameter Name

Required or Optional

Description

Enum or Example Values

Type

name

Required

Deal group name can contain a maximum of 256 characters, including spaces

Deal Group Name

String

notes

Optional

Notes can be used to describe the characteristics of the deal group

PG deals for CTV channel from publisher XYZ

String

advertisers

Required

Advertisers object defines whether the deal group is public (available to all advertisers) or private (available to a maximum of 10 advertisers)

 
"advertisers": {
    "advertiserIds": [
      3363017,
      3363019
    ],
    "allAdvertisers": false
  },

Object

advertiserIds

Required

advertiserIds is specified under advertisers

Advertiser IDs array defines which advertisers have access to the deal group:

  • To create a private deal group, in the advertiserIds parameter, list a maximum of 10 advertisers that'll have access to the deal group

  • To create a public deal group, leave the advertiserIds value empty

Important

Exception: Users with Specific Deal Access (SDA) set on account level can't create public deal groups.

3363017

Array

allAdvertisers

Required

allAdvertisers is specified under advertisers

All advertisers parameter defines whether the deal group is available to all advertisers:

  • To make the deal group available to all advertisers, set allAdvertisers value to true

  • To make the deal group available only to the advertisers specified in advertiserIds array, set allAdvertisers value to false

false

Boolean

status

Required

Status parameter specifies the status of the deal group

Note

Deal groups with active status can contain only eligible deals. Deals are eligible if they're accepted, active, and end in the future.

active or inactive

Enum

dealIds

Required

Deal IDs array defines which deals to add to the deal group. It consists of:

  • inventorySourceId: The inventory source that a deal uses.

  • dealId: The deal to include in the deal group

Important

To create a deal group, you must specify at least one deal. You can specify a maximum of 500 deals.

To include a deal in a deal group, the deal must be available to all advertisers that have access to the deal group.

 
"dealIds": [
    {
      "inventorySourceId": 23,
      "dealId": "DealIdExample1"
    },
    {
      "inventorySourceId": 7511,
      "dealId": "DealIdExample2"
    }
  ]

Array

Deal Group Update

Parameter Name

Required or Optional

Description

Enum or Example Values

Type

name

Required

Deal group name can contain a maximum of 256 characters, including spaces

When updating a deal group, specify a new name or use the existing name

Updated Deal Group Name

String

notes

Optional

Notes can be used to describe the characteristics of the deal group

PG deals for CTV channel from publisher XYZ

String

advertisers

Required

Advertisers object defines whether the deal group is public (available to all advertisers) or private (available to a maximum of 10 advertisers)

 
"advertisers": {
    "advertiserIds": [
      3363017,
      3363019
    ],
    "allAdvertisers": false
  },

Object

advertiserIds

Required

advertiserIds is specified under advertisers

Advertiser IDs array defines which advertisers have access to the deal group:

  • To update the advertiser access for a private deal group, in the advertiserIds parameter, list a maximum of 10 new or existing advertisers

  • To make a private deal group public, remove previously added advertisers and leave the advertiserIds value empty

    Important

    Exception: Users with Specific Deal Access (SDA) set on account level can't change private deal groups into public ones.

  • To make a public deal group private, in the advertiserIds parameter, list a maximum of 10 advertisers that'll have access to the deal group

Note

When updating a deal group, you can add only advertisers that have access to all deals in the group

3363019

Array

allAdvertisers

Required

allAdvertisers is specified under advertisers

All advertisers parameter defines whether the deal group is available to all advertisers:

  • To make a private deal group available to all advertisers, set allAdvertisers value to true

  • To make a public deal group available only to the advertisers specified in advertiserIds array, set allAdvertisers value to false

false

Boolean

status

Required

Status parameter specifies the status of the deal group

Note

Deal groups with active status can contain only eligible deals. Deals are eligible if they are accepted, active, and end in the future.

When updating a deal group, specify a new status or use the existing status

active or inactive

Enum

dealIds

Required

Deal IDs array defines which deals to add to the deal group and consists of:

  • inventorySourceId: The inventory source that a deal uses.

  • dealId: The deal to include in the deal group

Important

To update a deal group, you must keep at least one deal in the group. You can specify a maximum of 500 deals.

To include a deal in a deal group, the deal must be available to all advertisers that have access to the deal group.

 
"dealIds": [
    {
      "inventorySourceId": 23,
      "dealId": "DealIdExample1"
    },
    {
      "inventorySourceId": 7511,
      "dealId": "DealIdExample2"
    }
  ]

Array

Deal Group List

Parameter Name

Required or Optional

Description

Enum or Example Values

Type

ids

Optional

Filter deal groups by deal group ids

1, 2

Array

name

Optional

Filter deal groups by deal group name

This filter returns all deal groups with names that include the entered text, either as an exact match or as a partial match within a longer word or phrase

Deal Group Name

String

notes

Optional

Filter deal groups by deal group notes

publisher XYZ

String

statuses

Optional

Filter deal groups by deal group statuses, either active or inactive

active or inactive

Enum

advertiserIds

Optional

Filter deal groups by assigned advertiserIds

3363017, 3363019

Array

allAdvertisers

Optional

Filter deal groups by allAdvertisers value

false

Boolean

dealIds

Optional

Filter deal groups by an array of assigned dealIds

This filter returns only deal groups that include all of the deals listed in this array. These groups might also include other deals that aren't listed.

 
"dealIds": [
    {
      "inventorySourceId": 23,
      "dealId": "DealIdExample1"
    },
    {
      "inventorySourceId": 7511,
      "dealId": "DealIdExample2"
    }
]

Array

Endpoints

[{"api":"RTB Line Items Setup v3","titles":"LineItems"}]

Deal Groups

Deal Groups

RTB Line Items Setup v3

RTB Line Items Setup v3

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!