For details on API authentication, see Authentication for FreeWheel Demand APIs.
Overview
This document is intended for demand-side partners interested in automating the process by which creatives are uploaded to FreeWheel and associated to deal IDs. This document guides you through integrating with FreeWheel’s Demand Creative Management API and its intended use. Design of the Creative API has been informed by the IAB's Ad Management 1.0 and OpenDirect 2.0 specifications.
Note
While these specifications have informed the design, some modifications have been made.
The Demand Creative Management API v1.0.0 is a RESTful API that supports JSON. This section defines the JSON resource objects used by the API.
The Demand Creative Management API v1.0.0 has been designed for the Programmatic Guaranteed use case. It will be expanded to other use cases in the future.
The Demand Creative Management API V1 has complete feature parity with the previous Demand Creative API, allowing an integrated demand platform to upload and assign creatives to Programmatic Guaranteed deals. It also offers the following additional capabilities:
| Method | Capability |
|---|---|
| GET Deal Assignments | Retrieve a specific deal assignment by providing the dealid and dadid |
| DELETE Deal Assignments | Delete a deal assignment by providing the dealid and dadid |
| PUT Creatives | Update a creative that has already been uploaded |
Account IDs
The value for accountid is the same as that for your seatid or also commonly known as a buyer id, an ID identifying to FreeWheel which client is using a Demand-Side Platform (DSP).
When you create, update, retrieve, or delete any resource in the Demand Creative Management API, you must specify this ID in the request URL.
Clearance Levels and Audit Status
It is important to understand the relationship between the publishers' clearance levels and audit status settings so that you can make sure as many as your creatives can go live without delay.
Clearance Level settings
The clearance level, determined by the publisher, specifies the approval process a creative associated with a particular deal ID must complete before going live. This is set at the publisher clearance level and is inherited by the deal ID.
Buyers cannot modify clearance levels.
There are three possible values:
| Clearance Level Code | Clearance Level | Description |
|---|---|---|
| 0 | No Approval | The creative will not require any approval to go live. Many of our publishers will not usually set this as an option with their network. **This will be set by the publisher in their creative approval settings on their network |
| 1 | Restrictive | The creative must be approved to go live. **This will be set by the publisher in their creative approval settings on their network |
| 2 | Permissive | Creative approval is not required to go live. Audit status will always read as pending and begin delivering within the permissive clearance level, unless explicitly rejected by the publisher. The ad still serves regardless of pending audit status **This will be set by the publisher in their creative approval settings on their network |
| 3 | Not Supported | For deals created that have no clear approvals workflow, managed approvals will not be supported |
See also Deal Object below.
Audit Status settings
The audit status indicates the status in which the auditor has placed the creative.
• Pending Audit
• Approved
• Denied
• Not Supported
See also Audit Object below.
Using Clearance Level and Audit Status Settings (For Publisher Use ONLY)
The most common and easiest way to work with these settings is to specify your clearance level as Permissive. This keeps your creatives from being delayed because you do not have to wait for the audit status to be changed to Approved. Under the Permissive clearance level, a creative will only be stopped from going live if the audit status is specified as Denied. All Pending Audit and Approved creatives will go live under a Permissive clearance level.
If you want to make sure your creative is explicitly approved, set your clearance level to Restrictive.
Tip
When you update your creative, its creative approval status is reset to pending if the seller requires creative review. It is recommended that you only update creatives when absolutely necessary and that you inform the seller prior to doing so
Sequence Diagrams
Deal ID Workflow (Supports PG)
Assign a Creative to a Programmatic Deal ID Diagram
Assign a Creative to a Programmatic Deal ID Description
DSP
Uploads a creative via POST.
FreeWheel
Notifies the DSP that the creative has been added and returns an Ads Object representing the individual ad.
DSP
Assigns the creative to a Programmatic Deal ID via POST.
The creative only appears in the seller network after it has been assigned to a Programmatic Deal ID.
FreeWheel
Notifies the DSP that the deal assignment has been added and returns a Deal Assignment Object.
Retrieve and Delete Assignment Diagram
Note
In order to retrieve and delete deal assignments, you must include both the relevant dealid AND id in the request URL.
Retrieve and Delete a Deal Assignment Description
DSP
Retrieves the deal assignment via GET.
FreeWheel
Returns a Deal Assignment Object.
DSP
Deletes the deal assignment via DELETE.
FreeWheel
Sends an empty response.
Objects
Ads Object
An ad resource is an object representing each unique ad.
| Property | Description | Required? | Schema | GET | POST | PUT | DELETE |
|---|---|---|---|---|---|---|---|
| id | Unique ID of the ad provided by the buyer 50 characters maximum | Yes | string | Yes | Yes | No | N/A |
| video | Media Subtype Object that indicates this is a video ad and provides additional detail as such | Yes | object | Yes | Yes | Yes | N/A |
| name | Name of the ad | Yes | string | Yes | Yes | No | N/A |
| init | Timestamp of the original instantiation of this ad | N/A | datetime (ISO8601) | Yes | No | No | |
| audit | An object depicting the audit status of the ad; typically part of a quality/safety review process. | N/A | object array | Yes | No | No | No |
| lastmod | Timestamp of most recent modification to this ad (other than update to the Audit object) | N/A | datetime (ISO8601) | Yes | No | No | No |
Audit Object
| Property | Type | Description |
|---|---|---|
| status | integer | The audit status of the ad |
| init | datetime (ISO8601) | Timestamp of the original instantiation of this object |
| lastmod | datetime (ISO8601) | Timestamp of most recent modification to this object |
| feedback | string | One or more human-readable explanations as to reasons for rejection or any changes to fields for ad-quality reasons |
| sellerid | string | Unique ID representing the end seller of the Deal ID. It is the same ID as the publisher for your deal. The sellerid is pulled from: sellers.json documentation |
Audit Status Code
| Value | Status |
|---|---|
| 1 | Pending Audit |
| 3 | Approved |
| 4 | Denied |
| Not Supported |
Deal Assignments
A Deal Assignment assigns an ad with a Deal ID.
| Property | Description | Required? | Schema | GET | POST | PUT | DELETE |
|---|---|---|---|---|---|---|---|
| id | System-generated unique ID for the deal assignment | No | string | Yes | No | No | Yes |
| adid | Unique ID of the ad provided by the buyer. This is the ‘id’ submitted during POST /ads | Yes | string | Yes | Yes | No | Yes |
| dealid | The deal ID the ad will be assigned to. This must be a deal ID related to a Programmatic Guaranteed product. | Yes | string | Yes | Yes | No | Yes |
| deal | Contains additional metadata about the deal | object | Yes | No | No | No | |
| sellerid | Unique ID representing the end seller of the Deal ID. It is the same ID as the publisher for your deal. The sellerid is pulled from: sellers.json documentation | string | Yes | No | No | No | |
| clearancelevel | Indicates the seller creative clearance level setting for a particular deal ID. 0 = None. No approval process. 1 = Restrictive. The creative must be approved to go live. 2 = Permissive. Creative approval is not required to go live. 3=Not Supported | integer | Yes | No | No | No | |
| approvaltype | Indicates the seller approval type setting for a particular deal ID. 0 = None. No approval process. 1 = Managed. FreeWheel manages creative approval on behalf of the seller. 2 = Client. Sellers manage creative approval themselves. 3=Not Supported | integer | Yes | No | No | No |
List: Creative Subtypes – Audio/Video
| Value | Description | Supported |
|---|---|---|
| 1 | VAST 1.0 | Yes |
| 2 | VAST 2.0 | Yes |
| 3 | VAST 3.0 | Yes |
| 4 | VAST 1.0 Wrapper | Yes |
| 5 | VAST 2.0 Wrapper | Yes |
| 6 | VAST 3.0 Wrapper | Yes |
| 7 | VAST 4.0 | Yes |
| 8 | VAST 4.0 Wrapper | Yes |