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
Demand Campaign Manager API Workflow Description
Agency Buyer
- Creates a deal in the Demand-Side Platform (DSP).
Demand-Side Platform
- Creates a deal in Campaign Manager (via POST
/deals).
Campaign Manager
- Confirms that the deal is created and returns an
internal_deal_id.
Demand-Side Platform
- Creates a draft deal.
- 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
- Returns the forecast .
Demand-Side Platform
- Sends forecast metrics.
Agency Buyer
- Submits order to Marketplace to DSP.
Demand-Side Platform
- Orders Non-Guaranted deals in Campaign Manager via PUT
{internal_deal_id}:order. - Optional: edits a Non-Guaranteed deal via PATCH
deals/{deal_id}. - Optional: cancels the draft deal.
- Optional: deletes the draft deals with Ready or Generating status.
Campaign Manager
- 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:
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:
| 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:
| 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:
| 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:
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:
| 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:
|
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. |
|
| 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. |