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, 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 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 specifies the approval process a creative associated with a particular deal ID must complete before going live. The clearance level is set at the network level and is inherited by the deal ID.

📘

Buyers cannot modify clearance levels.

There are three possible values:

Clearance Level Code

Clearance Level

Description

1

Restrictive

The creative must be approved to go live.

2

Permissive

Creative approval is not required to go live.

The ad still serves regardless of audit status.

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

See also Audit Object below.

Using Clearance Level and Audit Status Settings

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

300300

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.

493493

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

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.

Property of Deal object

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.

Property of Deal object

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