"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

Creative Approvals

Whenever a Creative is created or edited it may be subject to an approval or submission process by one or more “Vendors”. Examples of Vendors:

  • Both Google and Xandr a Microsoft Company require all creatives to be submitted for a quality approval in advance of serving
  • Beeswax will use a proactive malware scanning system to assure Creatives do not contain harmful code
  • Measurement vendors like Nielsen and Comscore need Creatives registered with them in order to be tracked.

This document describes how the approval process works and how to use the API to check the status of an approval.

When is a Creative Approval Triggered?

A Creative approval process is triggered when any of the following occur:

  • A Creative is first created with all the assets needed to make it eligible to serve. For example, if a Creative is waiting on transcoded video it will not yet be eligible to serve.
  • A Creative’s creative_content is changed in any way or the click-through URL is changed. Fields unrelated to the content, such as notes or the name of the Creative will not trigger a re-approval.
  • A Creative is deleted
  • An active Creative is made inactive, or an inactive one is made active

Approval Process Overview

A list of all Creative Approval Vendors is available in the creative_approval_vendors table, accessible using a GET:

curl -X GET "http:/[path]/rest/view" -b cookies.txt -d '{"view_name":"creative_approval_vendors"}'

The set of vendors that will be queued up for any given approval depends on the creative_type of the creative, whether the vendor is marked as required, and whether additional, optional, vendors were requested by the user:

  • If a vendor is marked as required, and the creative_type matches the creative (or is set to -1) it will be set for approval.

Vendors that are not required, such as a measurement vendor, can be requested by adding the vendor declaration to the creative attributes of the Creative, as follows:

{"approval":
 {"vendor_id":
  [1,2]
 }
}

A new Creative Approval Queue object is created for each eligible vendor for each Creative, and the status is set to zero (NOT_SUBMITTED).

A list of the available creative statuses may be found in the creative_status view:

curl -X GET "http:/[path]/rest/view" -b cookies.txt -d '{"view_name":"creative_status"}'

A list of the current queue of approvals for a Creative may be found as follows:

curl -X GET "http:/[path]/rest/creative_approval_queue" -b cookies.txt -d '{"creative_id":<ID>}

A queue entry can have an Action, which reflects what to send to the vendor. Eligible actions include:

  • CREATE: Sent when a Creative is first created or when the content changes
  • PAUSE: Sent when a Creative was previously approved, but has now been set to inactive
  • RESUME: Sent when a Creative was previously paused, but has now been set to active
  • DELETE: When a Creative is deleted

These actions are needed because Malware vendors, for example, continuously scan creatives until we tell them to stop, and charge us per scan. For other vendors, like Google, the only action needed is CREATE.

Buzz de-duplicates requests in the case where the user takes multiple actions on a Creative before an approval is sent to a Vendor. For example, if the user activates and deactivates a Creative multiple times only a single "PAUSE" or "RESUME" will be sent.

How is the Creative Approval Queue Processed?

A periodic process runs to submit any CreativeApprovalQueue objects with a status of NOT_SUBMITTED to their respective approval vendor APIs. As a result of this process, the status of the CreativeApprovalQueue entries are set to either 1, PENDING or 5, ERROR.

Another periodic process checks the status of previously submitted Creatives by using the request_status of 1. If the vendor has completed their process and provides a helpful response, the CreativeApprovalQueue entries are updated to a status of 2, APPROVED or 4, REJECTED and any text messages relating to the process are stored in the approval_message field of the creative_approval_queue_history object.

Creative Approval and Inventory Sources

Certain inventory sources, such as Google and Xandr a Microsoft Company, will not allow Creative to run until they have been proactively approved. As a result, Buzz stores the approval status of the Creative against various inventory sources in the Creative's creative_attributes field, and the bidder will not serve these ads unless and until they have been marked as "approved".

Vendors marked as required that also have a set inventory_source field, will automatically be listed as pending in the creative attributes whenever a Creative is created or edited. For example, if inventory_sources 1 and 2 are both required, when a Creative is first created it will have an entry in the creative_attributes as follows:

{"approval":{"inventory_source":{"pending":[1,2]}}}

When a CreativeApprovalQueue is marked as APPROVED or REJECTED, if the vendor for which the queue entry belongs has an associated inventory_source, then the approval vendor attribute for that source is updated with the following syntax:

{"approval":{"inventory_source":{"approved":[<inventory_source_id>],"rejected":[<inventory_source_id>]}}}

When a Creative that has previously been approved for a given inventory source is changed, the status in the creative attribute changes back to PENDING.

Prohibiting Suspicious Creatives from Serving

The Creative object includes a field creative_status_id which is read-only for users. The creative_status_id field is interpreted by the bidder as “eligible to serve” where 0=not eligible, and 1=eligible. This overrides the active flag such that a Creative with active=1 and creative_status_id=0 will not serve.

By default, Buzz sets the creative_status_id to 1 for all Creatives.

If a malware scan sets the creative approval to status 10, SUSPICIOUS, the creative_status_id will be set to 0, meaning it cannot serve. There will be no way to set the creative_status_id back to 1 without administrative help, thus rendering the creative unable to serve or be edited using the UI or API.

Creative Approval Queue History

The CreativeApprovalQueue object contains the currently active approval request and/or response. If a user changes a Creative multiple times it can be helpful to see the history of approval requests. A second object, the creative_approval_queue_history, contains this data and is read-only. To GET the history of a single creative:

curl -X GET "http:/[path]/rest/creative_approval_queue_history" -b cookies.txt -d '{"creative_id":<ID>}