Build your own Campaign Manager

If you have UI/UX requirements specific to your business/application domain, you can build a custom campaign manager application on top of Moloco’s Management API . The management API allows you to perform ad campaign-related operations such as creating, updating and managing ad campaigns.

Authentication Prerequisites

The Management API requires an API key, please review the API Key and SSO credential management guide for information on generating an API key to programmatically access the API. This API key will be used to perform all management operations.

Limitations

Service	Limitation
End-user authentication, authorization, and management	You must use your existing Single Sign On solution to implement these features.
Notifications	Platform owners must handle their own user notifications.
Change History	The “Changed By“ field cannot be personalized and will display the System account when using BYOCM.

Adjustable Platform Features

All of the options in the table below can be configured independently for Sponsored Brands and Sponsored Display.

Platform Features

Sponsored Brands & Sponsored Display	Platform Configuration
Images	Supported image formats: jpeg/jpg, png, gif, webp Each Image format can be enabled or disabled independently. Set a maximum size in KB up to 314,572,800KB (300MB)
Videos	Supported resolutions: HLS, 720p, or 360p Maximum size in KB up to 314,572,800KB (300MB) Minimum and maximum duration in seconds.
Video Length	The minimum duration for videos is 5 seconds and the maximum is 60 seconds.
Aspect Ratio Validation	Enable or Disable video aspect ratio validation. Supports 16:9 and 9:16
Banner Images	Set a maximum image size in KB and minimum pixel dimensions.
Logo Images	Set a maximum image size in KB and minimum pixel dimensions.
Headline Text	Set a maximum text length
Call-to-Action (CTA)	Set custom text CTA (ex. Buy Now, Click, See More)
Campaign Review System	Enabled or Disabled the Campaign Review System

Asset Requirements

You must upload Video or Image assets before creating Sponsored Brands or Sponsored Display campaigns.

Uploading Images and Videos

The fields id, created_at, and updated_at must be left empty when creating a new creative assets or Landing Pages.

Image Assets: Please review the CreateImageAsset API reference for more information.
Video Assets: Please review the CreateVideoAsset API reference for more information.

Updating an existing Image or Video asset

Collect the image or video asset information and metadata using the corresponding APIs below.

Image Assets: Use the ReadImageAsset API to collect the latest information for the asset.
Video Assets: Use the ReadVideoAsset API to collect the latest information for the asset.

Image Asset Upload

Image Upload Configuration

Content-Type:

Use multipart/form-data (Do not use application/json)

Key Type:

When uploading Images use the following key types: file, image_asset, and object_key based on the upload method chosen.

🚧
The image files must meet all Platform configuration settings, such as the required image format, pixel dimensions, and file size.

File Requirements

Image Format: jpeg/jpg, png, gif, or webp
File Size: Maximum size 314,572,800KB (300MB)

Upload Options

We provide 2 methods to upload Image assets for Sponsored Brands and Sponsored Display, Upload by CDN and Upload by Session:

Option 1: Upload by CDN

There is 1 form data parameter named image_asset containing the CDN URL reference.

Form data parameters

Key	Type	Value
image_asset	JSON	See JSON below


{
  "title": "banner_title",
  "image_asset_type": "BANNER",
  "image_url": {
    "url": "<https://example.com/banner.png>",
    "file_name": "banner.png"
  }
}

Option 2: Upload by Session

Prerequisites: The Image file must be uploaded in advance using a bulk session upload before using this method.

There are 2 form data parameters named image_asset and object_key. The object_key is obtained by using the CreateBulkImageUploadSession API, the value is returned in the API response.

Form data parameters

Key	Type	Value
image_asset	JSON	See JSON below
object_key	Text	Obtained using the CreateBulkImageUploadSession API

Request a session URL from the MCM service by calling the CreateBulkImageUploadSessionRequest to obtain the upload_url. Provide the file names and mime type for each image asset.

{
  "files": [
    {
      "file_name": "<image-file-name.png>",
      "mime_type": "image/png"
    }
  ]
}

Use the CreateImageAsset API by passing in the object_key provided from Step 1 and the image_asset using JSON. Omit both the file and image_url objects when creating the request.

{
  "title": "Banner Image",
  "image_asset_type": "BANNER"
}

Video Asset Upload

Video Upload Configuration

Content-Type:
Use multipart/form-data (Do not use application/json)

Key Type:
When uploading videos, use key type file or object_key. Do not use both methods together in the same request.

File Requirements:

Format: MP4
Aspect Ratio: 16:9 and 9:16
Duration: 5 seconds minimum / 60 seconds maximum
Size: Maximum size 314,572,800KB (300MB)

Upload Options

Upload by Session

Prerequisites: The Video file must be uploaded in advance using the CreateBulkVideoUploadSession API to upload the file before using this method.

There is 1 form data parameter named object_key. The object_key is contained in the CreateBulkVideoUploadSession response.

Key	Type	Value
object_key	Text	Obtained using the CreateBulkVideoUploadSession API

Request a session URL from the MCM service by calling the CreateBulkVideoUploadSession API to obtain the upload_url.

{
  "files": [
    {
      "file_name": "string",
      "mime_type": "string"
    }
  ]
}

Use the CreateVideoAsset API by passing in the object_key provided in the CreateBulkVideoUploadSession API response from Step 1.

{
  "object_key": "string"
}

Campaign Review

By default your platform is configured to use an image asset and landing page review process. This process requires all assets and landing pages to be approved by the platform owner before a campaign can serve ads. You may disable the asset and/or landing page review systems, when disabled all assets and landing pages are auto-approved enabling campaigns to serve ads without any intervention.

Campaigns require a minimum of at least one Active asset and one landing page to activate. All assets and landing pages used in the campaign must be in the Approved and Active state in order to launch the ad campaign and serve ads. (See Campaign States for more information.)
By default the review status for each new asset will be set to the state IN_REVIEW. The asset(s) review status can be changed by approving or rejecting the asset. You may approve or reject an individual or group of assets and/or the landing page(s) of the campaign and leave comments using the Campaign Review APIs.
Please refer to the UpdateCampaignReviewsBulkRequest API reference for more information on how to update multiple asset and landing page reviews within one request.

Campaign Management

There are 2 fields labeled assets and landing_pages within each campaign, both fields are an array, these fields are used for managing Sponsored Brands and Sponsored Display Campaigns.

🚧
Approved assets are immutable. When making Decision API requests only the latest approved assets and landing page will be used.

Assets

You may choose to configure your platform matching requirements using 1 of the 2 configurations below:

Require a match for all asset dimensions (pixel size) for the specified inventory.

For example, if there are 2 inventories, 1 inventory using a 400x200 banner and 1 inventory using a 400x400 banner, the campaign should contain assets for both image dimensions, 400x200 and 400x400.

Require at least 1 matching dimension for the inventory.

For example, if there are 2 inventories, 1 inventory using a 400x200 banner and 1 inventory using a 400x400 banner, the campaign should contain at least 1 matching dimension, 400x200 or 400x400.

Assets may have up to 5 elements:

Banner

Banner assets should adhere to the sizes and aspect ratios set by the platform.

Video

Video assets should adhere to the size and aspect ratios set by the platform.

Logos

Logos should adhere to specific sizes and aspect ratios to ensure clarity and legibility.

Headlines

The headline should align with the creative assets to effectively communicate the campaign’s theme.

Call-to-Action

The CTA text should be clear and compelling to encourage user engagement.

Updating / Replacing Image Assets

Use one of the methods to upload a new image asset.
Use the ReadImageAsset API to collect the required information for the asset you wish to use.
Use the UpdateCampaign API with the collected data to replace the old image asset used in the campaign with the new asset.

Image Asset Validation

Banners: Must adhere to the pixel size and aspect ratios set by the platform.
Logos: Must adhere to specific pixel size and aspect ratios.

Exact Match

Exact Match Validation

By default, when uploading an asset, such as a banner image, the exact dimensions set from the inventory (i.e. 400x400 pixels) is required and validated. All assets marked as required by the platform such as the Banner, Logo, Headline, and Call-to-Action (CTA) must be included.

{
"campaign": {
  ...
  "ad_type": "BRAND",
  "assets": [
    {
      "id": "asset-400x200", // should be empty for create request
      "banner": { // Banner
        "creative_id": "banner_image_asset_1", // image_asset_id for BANNER
        "image_url": "https://moloco.com/400x200.png",
        "width": 400,
        "height": 200,
      },
      "logo": { // Brand Logo
        "creative_id": "logo_image_asset_1", // image_asset_id for LOGO
        "image_url": "https://moloco.com/logo.png"
      },
      "headline": { // headline
        "text": "headline"
      },
      "cta": { // call-to-action
        "text": "Click here"
      },
      "created_at": "time", // read-only
      "updated_at": "time", // read-only
    },
    {
      "id": "asset-400x400",
      "banner": { // Banner
        "creative_id": "banner_image_asset_2",
        "image_url": "https://moloco.com/400x400.png",
        "width": 400,
        "height": 400,
      },
      "logo": {
        "creative_id": "logo_image_asset_2", // image_asset_id for LOGO
        "image_url": "https://moloco.com/logo.png"
      },
      "headline": { // headline
        "text": "headline2"
      },
      "cta": { // call-to-action
        "text": "Buy Now"
      },
      "created_at": "time", // read-only
      "updated_at": "time", // read-only
    }
},
...

Aspect Ratio

Aspect Ratio Validation

To accept a range of image sizes platform owners may set the aspect ratio, minimum width, and minimum height instead of a static pixel size. Using this option requires populating the target_inventory_dimension field inside the banner object. This field sets the dimensions that the asset should target; the aspect ratio should align with the actual width and height of the image. Only the Banner and Headline are required when using Aspect Ratio validation.

{
  "campaign": {
    ...
    "ad_type": "BRAND",
    "assets": [
      {
        "id": "asset-400x200",
        "banner": { // Banner
          "creative_id": "banner_image_asset_1", // image_asset_id for BANNER
          "image_url": "https://moloco.com/400x200.png",
          "width": 200,
          "height": 100,
          "target_inventory_dimension": {
            "width": 400,
            "height": 200
          },
        },
        "headline": { // headline
          "text": "headline"
        },
        "created_at": "time", // read-only
        "updated_at": "time", // read-only
      },
      {
        "id": "asset-400x400",
        "banner": { // Banner
          "creative_id": "banner_image_asset_2",
          "image_url": "https://moloco.com/400x400.png",
          "width": 400,
          "height": 400,
          "target_inventory_dimension": {
            "width": 400,
            "height": 400
          },
        },
        "headline": { // headline
          "text": "headline2"
        },
        "created_at": "time", // read-only
        "updated_at": "time", // read-only
       },

Video Asset Validation

In order for a new campaign to move to the Active state, both the video transcoding process and the campaign approval process must be completed. The campaign will be placed in Pending status during transcoding. If an asset does not meet the requirements set by the platform the campaign will not activate. Validation is based on the following criteria:

Parameter	Validation Rule
Video Format	The source video is MP4.
Codec	The source video uses the H.264 codec.
Aspect Ratio	The aspect ratio is 16:9 or 9:16
Resolution	The source video adheres to the size and aspect ratios set by the platform.
Duration in seconds	Duration is between 5 seconds minimum and 60 seconds maximum.
Size in KB	File size is less than 314,572,800KB (300MB)

Video Asset Parameters

{
  "video_asset": {
    "ad_account_id": "acc-78910",
    "file_name": "campaign_video.mp4",
    "video_url": "https://cdn.moloco.com/video/campaign_video.mp4",
    "metadata": {
      "format": "MP4",
      "codec": "H.264",
      "aspect_ratio": "16:9",
      "resolution": "1920x1080",
      "duration_sec": 30,
      "size_kb": 18000000
    },
    "title": "Video Teaser"
  }
}

Landing Pages

The landing_pages field in the campaign specifies which page the shopper will be redirected to after clicking the asset. There are 3 options for Sponsored Brands and 2 options for Sponsored Display:

Landing Page Type	Sponsored Brands	Sponsored Display
Custom URL	Yes	Yes
Product Detail Page (PDP)	Yes	Yes
Product List Page (PLP)	Yes	No

🚧
Although the landing_pages field can store multiple landing pages, only the latest approved landing page will be used when a decision request is made, approved landing pages are immutable.

Landing Page Options

Custom URL

Enter any valid URL for the landing page.

{
        "id": "landing_page_custom_url",
        "type": "CUSTOM_URL",
        "custom_url_seting": {
          "url": "https://moloco.com" // URL to be redirected
        },
        "created_at": "time", // read-only
        "updated_at": "time", // read-only
      }

Product Detail Page

When redirecting to a specific product page, you must set the id for the item. Each item in your catalog feed has an associated id.

{
        "id": "landing_page_pdp",
        "type": "PRODUCT_DETAIL",
        "product_detail_setting": {
          "item_id": "catalog_item_id" // Catalog Item ID to be redirected
        },
        "created_at": "time", // read-only
        "updated_at": "time", // read-only
      }

Product List Page

Used to redirect to list of products in the campaign. The Product List is provided within the Decision API response, no additional settings required.

{
        "id": "landing_page_plp",
        "type": "PRODUCT_LIST",
        "product_list_setting": {
          // Nothing to set.
        },
        "created_at": "time", // read-only
        "updated_at": "time", // read-only
      }

Decision API Requests

Once a campaign is Active it may serve ads, please refer to the Decision API reference for more information on making decision requests for Sponsored Products, Sponsored Brands, and Sponsored Display campaigns.

Calling DecideAdBrands Tracker URLs

For a Sponsored Brands, when a campaign is selected by auction, the impressions, clicks, assets, and the items for advertising are tracked independently in the response.

When an impression or click occurs you must call the impression tracking URLs and the click tracking URLs provided within the response for each item and asset.

Tracker URL Example:

Calling DecideAdDisplay Tracker URLs

For a Sponsored Display, when a campaign is selected by auction, the impressions, clicks, and assets for advertising are tracked independently in the response.

When an impression or click occurs you must call the impression tracking URLs and the click tracking URLs provided within the response for each asset.

Tracker URL Example: