Introduction

Creative Management API v4 consolidates the capabilities of all previous Creative APIs, enabling you to use a single API to create creatives for all endpoints. With this one API you can make the following changes to your MRM Creative Library:

• Create creatives and renditions
• Update creatives and renditions
• Show creatives and renditions
• List creatives and renditions
• Delete creatives and renditions

At the same time, Creative Management API v4 offers features not previously available. With Creative Management API v4 you can now:

• List creatives configured in the way you want them to appear
• Ensure that your creative and rendition properties are not overridden by Media Detect
• Use a Universal Ad ID, a unique ID provided by a third-party registry

Creative Management API v4 helps you automate your workflows, reducing the need for manual inputs in MRM for traffickers and increasing the accuracy and efficiency of your ad ops teams. It prevents gateway timeouts by processing creatives asynchronously. Because Creative Management API v4 detects rendition properties automatically, requests are much simpler than those made to previous Creative APIs.

📘

Note

The Creative Management API v4 does not support XML requests or responses at this time. Requests must be made in JSON format and are returned in JSON.

Resources

URI(s)

Creative Management API v4 identifies two Uniform Resource Identifiers (URIs):

🚧

Note

Because of database capacity issues, the Creative Management API V4 returns a maximum of 50 creatives per page, even if you request a larger number than that.

Attributes

Creative Object

The following attributes are included in GET requests, except where indicated in the Comments column.

Message Object

Rendition Object

Ad Asset Store Status Object

Parameter Object

Formatting Requests with the Parameter Object

Your requests using the Parameter object should follow the following format:

"parameters": [
       { "name": "param name 1", "value": "param value 1" },
       { "name": "param name 2", "value": "param value 2" }
     ]

Additional Media Locations for Renditions

You might want to store the same rendition (physical media file) in multiple locations (e.g. different Content Delivery Networks) for redundancy purposes. To provide these additional locations for the same rendition, include the details in the additional_media_locations object in your [POST] request.

UniversalAdId Object

Another feature offered by Creative Management API v4 is the ability to identify a creative by means of a Universal Ad ID, a unique ID provided by a third-party registry.

If you want to create [POST] or update [PUT] a creative with a UniversalAdId, send a request containing the object below:

Clearing Repeated Fields for Create [POST] or Update [PUT] Creatives and Renditions

When you are creating [POST] or updating [PUT] creatives and renditions in Creative Management API v4, you may want to clear repeated fields. To do this, you must make specific requests. This prevents you from inadvertently clearing lists of Universal Ad IDs or parameters.

Clearing Universal Ad IDs

To clear all of the Universal Ad IDs include in your request the key clear_fields pointing to an array of strings outside of the Creative object, which contains the string universal_ad_ids.

You can use the clear_fields array outside of the Creative object without any Universal Ad IDs either with an empty array:

{
  "creative": {
    "universal_ad_ids": [],
    "base_ad_unit": "video" 
  },
  "clear_fields": [ "universal_ad_ids" ]
}

Or with no value at all:

{
  "creative": {
    "base_ad_unit": "video" 
  },
  "clear_fields": [ "universal_ad_ids" ]
}

Parameters

You can clear parameters in much the same way as you clear Universal Ad IDs. In your PUT request body, you can specify the parameters names and values to be updated. This ensures that any previously assigned parameters for that Creative are no longer assigned to it. However, if you send an empty parameters array or do not include parameters at all, the parameters for this creative will not be edited.

You can use a clear_fields array outside of the Creative object for parameters in the same way as described for universal_ids above.

Ambiguous Requests

If your request includes the string in clear_fields as well as values inside of the creative, you receive a 4xx error with a message stating:

"message": "request cannot include Universal Ad IDs when 'clear_fields' contains 'universal_ad_ids'"

Or:

"message": "request cannot include Parameters when 'clear_fields' contains 'parameters'"