Demand Creative Management API V1

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

Overview

This document is intended for demand-side parties 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.

📘

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

🚧

Important

FreeWheel currently supports a maximum of 30 creative renditions per VAST creative at one query per second for both POST and PUT methods. To improve performance, if possible, keep creative renditions to fewer than ten.

📘

Note

The approvals functionality included in the parameters below will be available with the 6.41 release scheduled for April 2021.

Collection of Ads

A collection of ads is an object containing one or more ads with additional metadata.

Property

Description

Required?

Schema

GET

POST

PUT

DELETE

count

The number of ads in this collection. Returned in the response of POST request to /ads

No

integer

N/A

N/A

N/A

N/A

ads

An array of ad resources

Yes

objects array

N/A

Yes

Yes

N/A

Ads

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

N/A

Yes

No

N/A

video

Media Subtype Object that indicates this is a video ad and provides additional detail as such

Yes

object

N/A

Yes

Yes

N/A

name

Name of the ad

Yes

string

N/A

Yes

No

N/A

init

Timestamp of the original instantiation of this ad

datetime (ISO8601)

audit

An object depicting the audit status of the ad; typically part of a quality/safety review process.

object array

lastmod

Timestamp of most recent modification to this ad (other than update to the Audit object)

datetime (ISO8601)

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.

See also: sellers.json documentation

Audit Status Code

Value

Status

1

Pending Audit

3

Approved

4

Denied

Deal Object

Property

Type

Description

clearancelevel

integer

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.

approvaltype

integer

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. The seller manages creative approval themselves

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

clearancelevel

approvaltype

AdCOM

Advertising Common Object Model is shared by OpenRTB, OpenDirect, and Ad Management. Ad Management version 1.0 has informed the design of the Demand Creative Management API. The AdCOM objects below are utilized in Demand Creative Management API.

AdCOM Media Objects

The Media group of objects defines an actual ad including reference to its creative and metadata to enable proper rendering, restrictions compliance, event tracking, and quality auditing. The following Media objects are supported in Demand Creative Management API: Video

Object: Video

This object provides additional detail about an ad specifically for video ads.

Property

Description

Required?

Schema

GET

POST

PUT

DELETE

ctype

The sub-type of the video creative. See List: Creative Subtypes - Audio/Video.

No

integer

N/A

Yes

No

N/A

curl

URL at which the creative markup will be found. Must be a valid HTTP URL.

Yes

string

N/A

Yes

Yes

N/A

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

Deal ID Workflow (Supports PG)

Assign

Retrieve and Delete Assignment

📘

Note

In order to retrieve and delete deal assignments, you must include both the relevant dealid AND id in the request URL.

Filtering

You can filter the listings you retrieve by:

  • Last updated before a specified date
  • Last updated after a specified date

Supported Filters

Parameter

Type

Description

auditstart

Timestamp

Beginning timestamp for the lastmod value from the Audit object, filtering returned ads by those last modified before the specified date, i.e, with a timestamp greater than this value.

auditend

Timestamp

Ending timestamp for the lastmod value from the Audit object, filtering returned ads by those last modified on or after the specified date, i.e, with a timestamp less than or equal to this value.

: :