For details on API authentication, see Authentication for FreeWheel Demand APIs.

Overview

The Demand Campaign Manager API supports non-guaranteed deal activation for contextually (standard attributes (content, geographic, device and the like) targeted deals.

You can use it to:

  • Create draft deals
  • Retrieve a Marketplace forecast, including forecasting opportunities, reach, and price ranges
  • Modify draft deals while they are in flight
  • Decide whether to activate/order the deal

At the end of the workflow you get an external_deal_ID against which you can target.

Demand Campaign Manager API Workflow

Sequence Diagram

14661466

Demand Campaign Manager API Workflow Description

Agency Buyer

  1. Creates a deal in the Demand-Side Platform (DSP).

Demand-Side Platform

  1. Creates a deal in Campaign Manager (via POST /deals).

Campaign Manager

  1. Confirms that the deal is created and returns an internal_deal_id.

Demand-Side Platform

  1. Creates a draft deal.
  2. Retrieves a forecast for the deal (via GET deals/{internal_deal_id}).

📘

Note

While draft deals are in flight, you can retrieve a list of draft deals and refresh forecast results.

Campaign Manager

  1. Returns the forecast .

Demand-Side Platform

  1. Sends forecast metrics.

Agency Buyer

  1. Submits order to Marketplace to DSP.

Demand-Side Platform

  1. Orders Non-Guaranted deals in Campaign Manager via PUT {internal_deal_id}:order.
  2. Optional: edits a Non-Guaranteed deal via PATCH deals/{deal_id}.
  3. Optional: cancels the draft deal.
  4. Optional: deletes the draft deals with Ready or Generating status.

Campaign Manager

  1. Confirms deal order.

Basic Attributes

Field

Description

Type

Guaranteed (G) or Non-Guaranteed (NG) deals)

Required in POST?

Notes

id

Campaign Manager internal deal ID.

Auto-generated by a database

integer

NG

No

Cannot be edited in draft or when deal is ordered.

deal_id

MRM- or Marketplace-generated public deal ID

string

NG

No

Cannot be edited in draft or when deal is ordered.

name

Deal's name

string

NG

No

Editable in draft or when deal is ordered.

advertiser

The advertiser targeted by that particular line item

Both

Editable in draft.

Not editable when deal is ordered.

status

Campaign Manager deal's status

enum

Possible values:

  • GENERATING
  • READY
  • ORDERED
  • DELETED
  • REVISION
  • CANCELLED
  • COMPLETED
  • AWAITING_APPROVAL (G)
  • APPROVED (G)
  • DECLINED (G)
*Note: G/NG - Guaranteed or Non-Guaranteed only*

Both

No

You can cancel via POST or use DELETE.

Cannot be edited in draft or when deal is ordered.

start_date

The start date of the deal

string

Possible formats:

  • date-time
  • ISO-8601

NG

Yes

Editable in draft or when deal is ordered, if existing and new start dates are both in the future.

end_date

The end date of the deal

string

Possible formats:

  • date-time
  • ISO-8601

NG

Yes

Editable in draft or when deal is ordered, if existing and new start dates are both in the future.

budget_model

The budget type of the deal

enum

Possible values:

  • IMPRESSION
  • CURRENCY

NG

Yes

Cannot be edited in draft or when deal is ordered.

currency_goal

The budget of the deal

float64

NG

Yes (if budgetmodel = currency)

Editable in draft if budgetmodel = currency.

Editable when deal is ordered only if the goal is being increased

secondary_goal

Sets a secondary goal for impressions and CPM, if primary goal is not achieved

String

G

No

Sample code:

"secondary_goal": {
"imp":0,
"cpm":{
"lower":0,
"upper":0
}
}

frequency_cap

The frequency cap of the deal

NG

Editable in draft or when deal is ordered.

seat

The open real-time-bidding (RTB) seat that the deal wants to use

string

NG

Yes

Editable in draft.

Cannot be edited when deal is ordered.

dsp_id

The DSP that this deal wants to use.

integer

NG

Yes

Editable in draft.

Cannot be edited when deal is ordered.

creative_duration

The creative duration that a buyer can specify

enum

Possible values:

  • 6
  • 15
  • 30
  • 60
  • 90
  • 120

Only one value can be used for targeting.

NG

Yes

Editable in draft or when deal is ordered.

transaction_type

The type of deal

enum

Possible values:

  • Non-Guaranteed
  • Guaranteed

NG

Cannot be edited in draft or when deal is ordered.

impression_goal

The budget of the deal

int64

NG

Cannot be edited in draft or when deal is ordered.

targeting

Targeting object that includes the FreeWheel standard attributes

NG

Editable in draft or when deal is ordered.

forecast

The forecast generated by the Recommendation Service (RS)

NG

Cannot be edited in draft or when deal is ordered.

pacing

SMOOTH_AS

G

audience_id

The audience identifier

string

G, NG

No

String length: 1~255

Advertiser Object

Field

Description

Type

Required in POST?

name

Advertiser's name

string

Yes

brand_name

The name of the product/brand that is being advertised (usually the same as advertiser name)

string

No

industry_id

The industry ID to which that advertiser belongs. This ID is retrieved from the Industry Reference API.

integer

Yes

Frequency Cap Object

Field

Description

Type

type

Only supports UNIVERSAL_HHID

enum

cap

The maximum number of times that a unique viewer may see ads for this deal during the specified interval.

integer

period

Defines the frequency cap intervals that the API supports. The frequency interval specifies the units in which the frequency count is expressed. For example, if a line’s frequency count is two and the interval is Day, display the ad to the same user a maximum of 2 times in the same calendar day.

enum

Possible values:

  • NONE
  • DAY
  • WEEK
  • MONTH

📘

Note

If the frequency cap period is NONE, the type and cap is not required.

If it's not NONE, the cap and type are required.

Forecast Object

Field

Description

Possible Values

forecast

The forecast generated by the Recommendation Service (RS)
forecast object:

status

The status of the Recommendation Service job.

  • NEW
  • IN_PROGRESS
  • SUCCESS
  • FAILURE (with failure reason)

cpm

Cost per thousand (CPM) range

opportunities

The estimated total opportunities provided to deliver an ad

digital_trp

Estimated percentage of your target audience that will be reached, expressed in target content rating points.

Targeting Object

See Targeting Reference API.