General API Questions

Why did FreeWheel build Demand Creative API V1c as opposed to updating FreeWheel Creative API v1.5?

There are three main reasons:

1. The previous API, FreeWheel Creative API v1.5, only supported the Programmatic Guaranteed use case. However, there are many use cases in which FreeWheel needs to process creatives from demand platforms. Therefore, the old version did not suffice.

2. FreeWheel Creative API v1.5 was completely bespoke. In order to build solutions that not only meet the requirements of our partners but benefit the industry as a whole, it is imperative that FreeWheel adopts industry standards where possible. This is why Demand Creative Management API V1 has been designed and built with the IAB’s Ad Management v1.0 specification in mind (although the assignment component is bespoke.)

3. The Creative API v1.5 was built on a legacy architecture that FreeWheel will not be supporting in the future. It was imperative that we build an API solution on a foundation that will best service our partners for years to come.

Is the Demand Creative Management API backward compatible with Creative API v1.5 ?

Yes, with one limitation. If you would like to assign a creative to a Programatic Guaranteed deal with the new API, it must be uploaded via the new API. Creatives that were uploaded via the previous API cannot be assigned to Programatic Guaranteed deals via the new API. All other functionality is backward compatible.

What new capabilities does the Demand Creative Management API provide?

The Demand Creative Management API has complete feature parity with the previous API, allowing an integrated demand platform to upload and assign creatives to PG deals. The following additional capabilities are provided:

What is the accountid? That parameter wasn’t in the previous API, nor is it in the IAB Ad Management API specification.

Correct, accountid was not a parameter in the previous API, nor is it in the IAB Ad Management specification. Two things to note here:

1. The `accountid` = `seatid`. When you create, update, retrieve, or delete any resource in the Demand Creative Management API, you must specify this ID in the request URL. The IAB Ad Management specification defined the following url path: **{baseUrl}/bidder/{bidderId}/[resource]**.

Should the audit status record 3 in the code sample below come with a sellerid to explicitly indicate to whom it is tied? Status record 1,  which accompanies it, explicitly indicates the seller. However, since an ad can be served to multiple sellers, should there be a sellerid for every audit status record?

https://api.freewheel.tv/demand/v1/accounts/1879/ads?count=20 
...
{
"id": "ltsjhpma",
"name": "ltsjhpma",
"init": "2021-12-21T12:08:40Z",
"lastmod": "2021-12-21T12:08:40Z",
"video":

{ .... }

,
"audit": [
{
"status": 3,
"init": "2021-12-21T12:08:40Z",
"lastmod": "2021-12-21T12:20:13Z"
},
{
"status": 1,
"init": "2021-12-21T12:08:40Z",
"lastmod": "2021-12-21T12:08:40Z",
"sellerid": "506334"
}
]
},

There are many use cases in which a sellerid is not returned with audit status records. Audit status records that do not include a sellerid receive approval on behalf of the seller from the global approvals network. To avoid a confusion of sellerids, only one network ID providing approval is included in any response's audit status object.

Sometimes a status is returned multiple times with the same lastmod timestamp, as in the audit status record 3 in the example below. Is that expected behavior?

https://api.freewheel.tv/demand/v1/accounts/2165/ads?count=20
...
{
"id": "xfsygn0l",
"name": "xfsygn0l",
"init": "2021-11-30T17:16:10Z",
"lastmod": "2021-11-30T17:16:10Z",
"video":

{ ... },
"audit": [
{
"status": 1,
"init": "2021-11-30T17:16:10Z",
"lastmod": "2021-11-30T17:16:10Z"
},
{
"status": 3,
"init": "2021-11-30T17:16:10Z",
"lastmod": "2021-12-01T10:06:29Z",
"sellerid": "174057"
},
{
"status": 3,
"init": "2021-11-30T17:16:10Z",
"lastmod": "2021-12-01T10:06:29Z",
"sellerid": "174057"
},
{
"status": 3,
"init": "2021-11-30T17:16:10Z",
"lastmod": "2021-12-01T10:06:29Z",
"sellerid": "174057"
},
{
"status": 3,
"init": "2021-11-30T17:16:10Z",
"lastmod": "2021-12-01T10:06:29Z",
"sellerid": "174057"
}
]
},

Those are unexpected duplicated approval outputs in the creative service response to the demand component.

FreeWheel is looking into a fix for this.

How many creative renditions should I have for good performance?

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, keep creative renditions to fewer than ten.

Pre-Approval Questions

What's the difference between an underlying creative and a creative?

A creative is one DSP-submitted creative ID. Every creative undergoes processing by FreeWheel to identify whether it is unique. The internal logic for determining creative uniqueness differs by the age and type of the creative.

For the purposes of PMP pre-approval, uniqueness is calculated from the creative's inline VAST tag information. VAST tags change when the creative's media file URL changes; this can occur with manual or rotating VAST changes. When the VAST tag changes of a creative changes, but is submitted with the same creative ID, one creative ID now has multiple variants. These variants are referred to as underlying creatives.

FreeWheel categorizes each variant as an underlying creative so publishers can keep track of which creative version they wish to approve or deny.

Why are there two audit statuses?

The audit status reflects the general standing of submitted creatives for a deal. This value merges the statuses of all underlying creatives to provide a quick overview of a publisher's evaluation.

If multiple creatives are associated with a pre-ingest deal, its audit status can be partial. A partial audit status indicates that multiple underlying creatives are associated with the uploaded creative, and that their individual audit statuses differ. This concept is represented as statusispartial .

The merging logic of status follows a priority order from least to most restrictive: Approved > Pending > Rejected.

In what situations do I need to submit creatives for pre-approval?

For Programmatic Guaranteed deals (PG), creatives always require pre-approval.

For Private Marketplace (PMP) deals, publishers can choose to require pre-approval. Each deal pulled will indicate whether or not pre-approval is allowed.