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 V1 and its intended use. Design of this API has been informed by the IAB's Ad Management 1.0 and OpenDirect 2.0 specifications.
The Demand Creative Management API V1 is a RESTful API that supports JSON. This page defines the JSON resource objects used by the API.
The Demand Creative Management API V1 has been designed for the Programmatic Guaranteed (PG) use case. It also supports Private Marketplace (PMP) deals that require pre-approval.
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 PG and PMP pre-approval 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 |
| GET Creatives without Account ID | Retrieve all creatives to check creative approval status, regardless of account |
| GET Underlying Creatives | Retrieve underlying creatives for an ad to see each creative's audit status |
Account IDs
The value for account_id is the same as that for your seat id, also commonly known as a buyer id. This ID tells FreeWheel which client is using a Demand-Side Platform (DSP).
When you create, update, or delete any resource in the Demand Creative Management API V1, you must specify this ID in the request URL. Retrieving resources generally requires an account ID, with the exception of Retrieve All Creatives Without Account ID.
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.
Note
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
Audit status can be partial for PMP pre-approval deals. A partial audit status indicates that multiple underlying creatives are associated with the uploaded creative, and that their individual audit statuses differ. For these deals, the audit status represents a merged approval status. The merging logic of status follows a priority order from least to most restrictive: Approved > Pending > Rejected.
| Approved | Pending | Rejected | Audit Status status | Is Status Partial?statusispartial |
|---|---|---|---|---|
| 3 | 0 | 0 | Approved | False |
| 2 | 1 | 0 | Approved | True |
| 2 | 0 | 1 | Approved | True |
| 1 | 2 | 0 | Approved | True |
| 1 | 1 | 1 | Approved | True |
| 1 | 0 | 2 | Approved | True |
| 0 | 3 | 0 | Pending | False |
| 0 | 2 | 1 | Pending | True |
| 0 | 1 | 2 | Pending | True |
| 0 | 0 | 3 | Rejected | False |
Whenstatusispartial is true and the deal is not approved, the DSP needs to check underlying creatives for the deal to avoid interruptions to serving. To determine the audit status of each underlying creative, Retrieve Underlying Creatives.
See also Troubleshoot Partial Approval for PMP Pre-Approval Deals 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.
Demand Creative Management API V1 Workflows
Assign a Creative to a Deal ID
DSP
- Uploads a creative via POST.
FreeWheel
- Notifies the DSP that the creative has been uploaded and returns an ads object representing the individual ad.
DSP
- Assigns the creative to a PG or PMP pre-approval Deal ID via POST.
Note
The creative only appears in the seller network after it has been assigned to a Deal ID.
FreeWheel
- Notifies the DSP that the deal assignment has been added and returns a deal assignment object.
Retrieve and Delete Assignment
Note
In order to retrieve and delete deal assignments, you must include both the relevant
dealidANDadidin the request URL.
DSP
- Retrieves the deal assignment via GET.
FreeWheel
- Returns a deal assignment object.
DSP
- Removes the deal assignment from the creative via DELETE.
FreeWheel
- Sends an empty response.
Troubleshoot Partial Approval for PMP Pre-Approval Deals
DSP
- Requests a list of all creatives via GET.
FreeWheel
- Returns a list of all creatives. For some deals,
statusispartial=1 appears in the audit object. This indicates partial audit approval status for the deal.
DSP
- Enters
accountidandadidto investigate a specific deal with partial approval. Requests underlying creatives for the deal via GET.
FreeWheel
- Returns a list of underlying creatives for a specific deal with the audit status of each creative.
Objects
Ads Object
An ad resource is an object representing each unique ad.
| Property | Description | Required? | Schema | GET | POST | PUT | DELETE |
|---|---|---|---|---|---|---|---|
| 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 |
| id | Unique ID of the ad provided by the buyer 50 characters maximum | Yes | string | Yes | Yes | No | N/A |
| init | Timestamp of the original instantiation of this ad | N/A | datetime (ISO8601) | Yes | No | No | N/A |
| lastmod | Timestamp of most recent modification to this ad (other than update to the Audit object) | N/A | datetime (ISO8601) | Yes | No | No | No |
| name | Name of the ad | 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 |
Audit Object
| Property | Type | Description |
|---|---|---|
| feedback | string | One or more human-readable explanations as to reasons for rejection or any changes to fields for ad-quality reasons |
| init | datetime (ISO8601) | Timestamp of the original instantiation of this object |
| lastmod | datetime (ISO8601) | Timestamp of most recent modification to this object |
| 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 |
| status | integer | The audit status of the ad |
| statusispartial | boolean | The partial audit status that merges the statuses of an ad 0 = False 1 = True |
Audit Status Code
| Value | Status |
|---|---|
| 1 | Pending Audit |
| 3 | Approved |
| 4 | Denied |
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 |
Underlying Creatives
Underlying creatives are a collection of creatives assigned to a single ad, each with their own audit status.
| Property | Description | Schema | GET |
|---|---|---|---|
| externalcreativeid | Identifier for the underlying creative of the video ad submitted in the ads endpoint | string | Yes |
| vastcontenturl | URL of the actual creative that the end user will watch | string | Yes |
| audit | Audit status 3 = Approved 1 = Pending 4 = Rejected | object array | Yes |
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 |