Follow us on Twitter

Commerce Media & Deeplink campaigns API

The Zeropark Commerce Media & Deeplink campaigns API provided below allows you to view and manage your campaigns, e.g. create new ones or edit the existing ones. 

Below you’ll find a common model for such scenarios along with a list of endpoints to be used.

Campaign types and traffic targeting options

Commerce Media

Commerce Media campaigns enable redirecting users looking for specific brands directly to the brand’s website.

This campaign type allows two traffic targeting options:

  • RON (Run-of-Network) campaigns are recommended when launching new campaigns in Zeropark. This is the broadest targeting type available, allowing your campaigns to buy traffic from all the available sources.
  • Target campaigns where are the individual placements your ad appears on. Target campaigns let you narrow down your targeting just to the placements you select. A list of targets needs to be provided for such campaigns to start buying traffic.

Deeplink

Deeplink (also known as Product traffic) is a type of advertising inventory available in Zeropark. It allows for streamlining visitors coming from broad product queries directly to relevant product offers.

This campaign type is an extension of Commerce Media campaigns.

API Sections

The campaign model is divided into several parts, each of which is responsible for its parameters. The fields of each section with descriptions and examples can be found below.

1. Type

  • Field name: “type”, Field type: Enum

This field is responsible for specifying the campaign type. Please note that, once a campaign has been created, it is not possible to change the above value. Possible values are RON and TARGET.

EXAMPLE:

"type": "TARGET"

2. Traffic destination

Moved to the targeting section.

3. ID

  • Field name: “type”, Field type: UUID

This value is responsible for identifying the individual campaign. It is returned along with other campaign details, and must also be specified when editing a campaign. It should not be specified when creating a new campaign.

EXAMPLE:

"id": "2c727e90-92e1-11eb-b7b3-acde48001122"

4. Budgets

  • Field name: “budgets”

This value is responsible for identifying the individual campaign. It is returned along with other campaign details, and must also be specified when editing a campaign. It should not be specified when creating a new campaign.

EXAMPLE:

"budgets": {
 "bid": 0.5, 
 "campaignBudget": {
   "type": "UNLIMITED"
 },
 "dailyBudget": {
   "type": "LIMITED",
   "amount": 20
 },
 "targetBudget": {
   "type": "UNLIMITED"
 }
}

4.1. Budgets section description

  1. Bid - this field is responsible for the bid of the campaign.
    • Field name: “bid”, Field type: Numeric
  2. Campaign budget - this field is responsible for the total budget of the campaign.
    • Field name: “campaignBudget”
    1. Type - possible values are LIMITED and UNLIMITED.
      • Field name: “type”, Field type: Enum
    2. Amount - numeric value is required in case the selected Type is LIMITED. Otherwise, the field should be omitted.
      • Field name: “amount”, Field type: Numeric, Required: False
  3. Daily Budget - this field is responsible for the daily budget of the campaign.
    • Field name: “dailyBudget”
    1. Type - possible values are LIMITED and UNLIMITED.
      • Field name: “type”, Field type: Enum
    2. Amount - a numeric value is required in case the selected Type is LIMITED. Otherwise, the field should be omitted.
      • Field name: “amount”, Field type: Numeric, Required: False
  4. Target budget - this field is responsible for the daily budget of the campaign.
    • Field name: “targetBudget”
    1. Type - possible values are LIMITED and UNLIMITED.
      • Field name: “type”, Field type: Enum
    2. Amount - numeric value is required in case the selected Type is LIMITED. Otherwise, the field should be omitted.
      • Field name: “amount”, Field type: Numeric, Required: False

5. General

  • Field name: “general”

This section is responsible for the basic parameters of the campaign.

EXAMPLE:

"general": {
 "name": "My first campaign", 
 "afterApprovalState": "ACTIVE"
}

5.1. General section description

  1. Name - the name of your campaign.
    • Field name: “name”, Field type: String
  2. After approval state - the state your campaign will assume once it’s accepted by our approval team. Possible values are ACTIVE and PAUSED.
    • Field name: “afterApprovalState”, Field type: Enum
  3. State - the current state of your campaign. A field used only when reading a campaign. Changing the value will not change the campaign state either when editing or creating the campaign. Appropriate endpoints are provided for performing state change actions. Possible values are: PENDING, ACTIVE, PAUSED, REJECTED, DELETED, DRAFT and ARCHIVED.
    • Field name: “state”, Field type: Enum

6. Offer

  • Field name: “offer”

This section is responsible for the basic parameters of the campaign.

EXAMPLE

"offer": { 
 "url": "https://codewise.com?cid={cid}", 
 "payout": {
  "type": "AUTO" 
 }
}

6.1. Offer section description

  1. URL - the destination url of your campaign. Please remember that {product_url} token is mandatory for Product Deeplink campaigns.
    • Field name: “url”, Field type: String
  2. Conversion payout - conversion payout settings for your campaign. If your affiliate network doesn't pass information about the payout, you can input it manually.
    • Field name: “payout”
    1. Type - possible values are MANUAL and AUTO.
      • Field name: “type”, Field type: Enum
    2. Value - numeric value is required in case the selected Type is MANUAL. Otherwise, the field should be omitted.
      • Field name: “value”, Field type: Numeric, Required: False

7. Timing

  • Field name: “timing”

In this section, you can configure how often the offer can be displayed to the same customer and at what times the campaign should be active.

EXAMPLE:

"timing": {
 "frequencyFilter": {
   "value": "HOUR"
},
 "dayParting": {
   "scheduled": "ON",
   "schedule": {
     "MON": [
       0,
       1,
       2,
       3,
       4
     ],
     "SUN": [
       20,
       21,
       22,
       23
     ]
   },
   "timeZone": {
     "id": "UTC"
   }
 }
}

7.1 Timing section description

  1. Frequency filter - defines how often your ad can be displayed to the same visitor.
    • Field name: “frequencyFilter”
    • Value - possible values are OFF, FIVE_MINUTES, TEN_MINUTES, FIFTEEN_MINUTES, HALF_HOUR, HOUR, THREE_HOURS, SIX_HOURS, TWELVE_HOURS and DAY. It is not possible to choose a custom value.
      • Field name: “value”, Field type: Enum
  2. Day parting - defines in which hours, in a particular timezone, your campaign should be running.
    • Field name: “dayParting”
    1. Scheduled - defines whether the frequency filter is active. Possible values are ON and OFF.
      • Field name: “scheduled”, Field type: Enum
    2. Schedule - defines in what hours on what days your campaign should be running. Should be provided as a json map/dictionary, where allowed keys are MON, TUE, WED, THU, FRI, SAT, SUN and possible values are numbers from 0 to 23 presented as an array. If the Scheduled field is configured as OFF, this field, along with Timezone, should be omitted.
      • Field name: “schedule”, Required: False
    3. Timezone - this field defines a particular timezone for dayparting hours in case the frequency filter is on. Otherwise, this field, along with Schedule, should be omitted.
      • Field name: “timeZone”, Required: False
      • Id - Name of the preferred timezone.
        • Field name: “id”, Field type: String

8. Targeting

  • Field name: “targeting”

This section is responsible for the detailed selection of the campaign audience. Individual targeting subgroups are grouped by appropriate keys, which are described in detail below.

EXAMPLE:

"targeting": {
"DEVICE": {
   "deviceFilters": {
     "devices": [
       "MOBILE",
       "DESKTOP"
     ],
     "desktopOses": [
       {
         "os": "MACOS",
         "version": {
           "min": "MIN",
           "max": "MAX"
         }
       }
     ],
     "desktopBrowsers": [
       "CHROME",
       "SAFARI"
     ],     "mobileOses": [
       {
         "os": "IOS_PHONE",
         "version": {
           "min": "MIN",
           "max": "MAX"
         }
       }
     ],
     "mobileBrowsers": [
       "CHROME",
       "SAFARI",
       "OPERA"
     ]
   }
 }, "SEARCH": {
     "trafficDestination": "PRODUCT_DEEPLINK"
 }, "LOCATION": {
  "mode": "ON",
  "regions": {
   "type": "INCLUDED",
   "names": [
     {
       "name": "FLORIDA"
     }
   ]
 }
,
  "cities": {
   "type": "EXCLUDED",
   "names": [
     {
       "name": "Miami",
       "region": "FLORIDA"
     }
   ]
 }
},
 "GEO": {
   "country":
 {
     "code": "US"
   }
 },
 "BRAND": {
   "definition": "PREDEFINED",
   "id": "15fa0202-0702-4201-a4b3-969fb3dca99d",
   "imageId": "31890955-bfe6-4056-a208-051a5f659a03",
   "brandUrl": "apple.com",
   "name": "Apple"
 },
"PLACEMENTS": {
"categories": [
    {      "category": "Buy_Now_Pay_Later",
       "status": "SELECTED_PLACEMENTS",
       "bid": 2.5,
       "placements": [
         {
           "placement": "Affirm",
           "status": "DISABLED"
         },
         {
           "placement": "Afterpay",
           "status": "DISABLED"
         },
         {
           "placement": "Clearpay",
           "status": "DISABLED"
         },
         {
           "placement": "Klarna",
           "status": "ENABLED"
         },
         {
           "placement": "Laybuy",
           "status": "DISABLED"
         },
         {
           "placement": "PayWithFour",
           "status": "DISABLED"
         },
         {
           "placement": "Sezzle",
           "status": "DISABLED"
         },
         {
           "placement": "Wantlocker",
           "status": "DISABLED"
         },
         {
           "placement": "Zilch",
           "status": "ENABLED"
         },
         {
           "placement": "Zip",
           "status": "DISABLED"
         },
         {
           "placement": "Other",
           "status": "DISABLED"
         }
       ]
     },
     {
       "category": "MSN",
       "status": "DISABLED"
     },
     {
       "category": "Tiles/Speed_Dial",
       "status": "SELECTED_PLACEMENTS",
       "placements": [
         {
           "placement": "Avast_and_AVG",
           "status": "DISABLED"
         },
         {
           "placement": "Huawei_and_Petal_Browsers",
           "status": "ENABLED"
         },
         {
           "placement": "Opera",
           "status": "ENABLED"
         },
         {
           "placement": "Smart_TV",
           "status": "DISABLED"
         },
         {
           "placement": "Other",
           "status": "DISABLED"
         }
       ]
     },
     {
       "category": "Coupon",
       "status": "ENABLED"
     },
     {
       "category": "Email",
       "status": "DISABLED"
     },
     {
       "category": "Knowledge_Panel",
       "status": "DISABLED"
     },
     {
       "category": "Browser_Autocomplete",
       "status": "ENABLED"
     },
     {
       "category": "Commerce_Content",
       "status": "ENABLED",
       "bid": 1.0
     },
     {
       "category": "Social",
       "status": "ENABLED"
     },
     {
       "category": "Ad_Network",
       "status": "DISABLED"
     }
   ]
 }  
}

The once-used "BASE" section is now split into "ADULTHOOD" and "DEVICE" sections.

- "SEARCH" field refers to the Traffic destination section

8.1. Targeting section description

  1. Device - the section allows you to select devices for your campaign.
    • Field name: “DEVICE”
    • Device filters - the section is responsible for detailed device selection.
      • Field name: “deviceFilters”
      1. Devices - this section is responsible for device type selection. It can be either an array containing one of the following values DESKTOP, MOBILE or an array containing both of them.
        • Field name: “devices”, Field type: Enum Array
      2. Desktop OSes - in this section you can configure detailed preferences for desktop operating systems. The field should take an array of the following structures.EXAMPLE:
        {
 "os": "{name}",
 "version": {
   "min": "{version.min}",
   "max": "{version.max}"
 }
}
        Where possible values for {name} are WINDOWS, MACOS, LINUX and OTHER. For {version.min} one can use either MIN enum value or some particular value, appropriate to the chosen system, passed as string. For {version.max} one can use either MAX enum value or some particular value, appropriate to the chosen system, passed as string.
        • Field name: “desktopOses”
      3. Desktop browsers - in this section you can configure preferences for desktop browsers. The permissible values that can be included in the array are SAFARI, CHROME, FIREFOX, EDGE, IE and OTHER.
        • Field name: “desktopBrowsers”, Field type: Enum Array
      4. Mobile OSes - in this section you can configure detailed preferences for mobile operating systems. The field should take an array of the following structures.EXAMPLE:
        {
 "os": "{name}",
 "version": {
   "min": "{version.min}",
   "max": "{version.max}"
 }
}
        Where possible values for {name} are IOS_PHONE, IOS_TABLET, ANDROID_PHONE, ANDROID_TABLET and OTHER. For {version.min} one can use either MIN enum value or some particular value, appropriate to the chosen system, passed as string. For {version.max} one can use either MAX enum value or some particular value, appropriate to the chosen system, passed as string.
        • Field name: “mobileOses”
      5. Mobile browsers - in this section you can configure preferences for mobile browsers. The permissible values that can be included in the array are SAFARI, CHROME, FIREFOX, OPERA, FACEBOOK, ANDROID, SAMSUNG, UC_BROWSER and OTHER.
        • Field name: “mobileBrowsers”, Field type: Enum Array
  2. Geo - this section allows you to select the country for your campaign.
    • Field name: “GEO”
    1. Country - in this section you should provide code of the country selected for your campaign.
      • Field name: “country”
    2. Code - you can only provide one country code for the campaign, for example "code": "US".
      • Field name: “code”, Field type: String
  3. Location - the section is responsible for selecting preferred regions and cities for the campaign to reach, or for excluding them.
    • Field name: “LOCATION”
      1. Mode - can be either ON or OFF. In case location targeting is disabled, the following fields can be omitted.
        • Field name: “mode”, Field type: Enum
      2. Regions - used to select regions from which to prefer or exclude traffic.
        • Field name: “regions”
        1. Type - can be either INCLUDED or EXCLUDED.
          • Field name: “type”, Field type: Enum
        2. Names - the field should take an array of the following structures.EXAMPLE:
          {
 "name": "{name}"
}
          Where for the {name} you should provide the name of the region (in uppercase).
          • Field name: “names”
      3. Cities - used to select cities from which to prefer or exclude traffic.
        • Field name: “cities”
        1. Type - can be either INCLUDED or EXCLUDED.
          • Field name: “type”, Field type: Enum
        2. Names - the field should take an array of the following structures.EXAMPLE:
          {
 "name": "{name}",
 "region": "{region}"
}
          Where for the {name} you should provide the name of the city, and for the {region} you should provide its region (in uppercase).
  4. Brand - the section allows you to select a specific brand your campaign will advertise. Please remember, that you can choose it only once when creating the campaign. Editing is not possible. If you want to create a new brand using our API, you need to provide its definition as CUSTOM, include brandUrl and name. Additionally, you can use the imageId of any of your existing brands. When you don’t want to reuse any of the existing icons, just skip this field, and a default blank image will be used.
    • Field name: “BRAND”
    1. Definition - possible values are PREDEFINED and CUSTOM. When using the PREDEFINED option, you can use a brand that already exists in our system. When using the CUSTOM option, you can either create a new brand, or reuse a brand that has already been created for one of your campaigns.
      • Field name: “definition”, Field type: Enum
    2. ID - ID of the brand that you want to use.
      • Field name: “id”, Field type: UUID
    3. Image ID - image ID of the brand that you want to use.
      • Field name: “imageId”, Field type: UUID
    4. Brand URL - URL of the brand that you want to use.
      • Field name: “brandUrl”, Field type: String
    5. Name - name of the brand that you want to use.
      • Field name: “name”, Field type: String
  5. Search - this section allows you to configure the traffic of your campaignThis field is responsible for differentiating Commerce Media campaigns from Deeplink campaigns. Please note that, once a campaign has been created, it is not possible to change the above value. The only possible value here is PRODUCT_DEEPLINK.
    "trafficDestination": "PRODUCT_DEEPLINK'
    • Field name: "trafficDestination". Field type: Enum

    For Commerce Media campaigns, this field has to be skipped.

  6. Placements - the section allows you to select Placement Categories for your campaign
    • Field name: “PLACEMENTS”
    • Placement Category - section that allows you to Enable/Disable entire Placement Categories for your campaigns.
      • Field name: “categories"

Placements dictionary

https://panel.zeropark.com/api/v2/placements

This endpoint allows you to get all available Placement Categories for Commerce Media campaigns.

When creating a campaign, you have to specify the status (ENABLED/DISABLED/SELECTED_PLACEMENTS) for each Placement Category:

  • ENABLED means that you want to buy all Placements within a specific Placement Category.
  • DISABLED means you don’t want to buy any placement from a specific Placement Category.
  • SELECTED_PLACEMENTS means that you want to buy traffic from a subset of Placements within a specific Placement Category and block the rest of them at the same time.

Remember that it's now possible to specify a custom bid per placement category, simply by using the "bid" property (see example below).

If a Placement Category has a subset of Placements, you can optionally specify Placement status (ENABLED/DISABLED) for each of them. If not specified, Placements are set to ENABLED by default.

Full request model

Below you can see an example of a full request to the API for Zeropark Commerce Media campaigns.

{
    "type": "TARGET",
    "traffic": "SEARCH",
    "general": {
        "name": "Deeplink Campaign",
        "afterApprovalState": "ACTIVE"
    },
    "offer": {
        "url": "https://apple.com?cid={cid}&name={campaign_name}&id={campaign_id}&target={target}&product={product_url}",
        "payout": {
            "type": "MANUAL",
            "value": 25
        }
    },
    "timing": {
        "frequencyFilter": {
            "value": "HOUR"
        },
        "dayParting": {
            "scheduled": "ON",
            "schedule": {
                "MON": [
                    0,
                    1
                ],
                "SUN": [
                    22,
                    23
                ]
            },
            "timeZone": {
                "id": "Atlantic/Azores"
            }
        }
    },
    "budgets": {
        "bid": 0.5,
        "buyingModel": "ASAP",
        "campaignBudget": {
            "type": "UNLIMITED"
        },
        "dailyBudget": {
            "type": "LIMITED",
            "amount": 25
        },
        "targetBudget": {
            "type": "UNLIMITED"
        }
    },
    "targeting": {
        "DEVICE": {
            "deviceFilters": {
                "devices": [
                    "MOBILE",
                    "DESKTOP"
                ],
                "desktopOses": [
                    {
                        "os": "MACOS",
                        "version": {
                            "min": "MIN",
                            "max": "11.0"
                        }
                    }
                ],
                "desktopBrowsers": [
                    "SAFARI",
                    "CHROME"
                ],
                "mobileOses": [
                    {
                        "os": "IOS_PHONE",
                        "version": {
                            "min": "12.0",
                            "max": "MAX"
                        }
                    }
                ],
                "mobileBrowsers": [
                    "SAFARI",
                    "OPERA"
                ]
            }
        },
        "SEARCH": {
            "trafficDestination": "PRODUCT_DEEPLINK"
        },
        "LOCATION": {
            "mode": "ON",
            "regions": {
                "type": "INCLUDED",
                "names": [
                    {
                        "name": "FLORIDA"
                    }
                ]
            },
            "cities": {
                "type": "EXCLUDED",
                "names": [
                    {
                        "name": "Miami",
                        "region": "FLORIDA"
                    }
                ]
            }
        },
        "GEO": {
            "country": {
                "code": "US"
            }
        },
        "BRAND": {
            "definition": "PREDEFINED",
            "id": "15fa0202-0702-4201-a4b3-969fb3dca99d",
            "imageId": "31890955-bfe6-4056-a208-051a5f659a03",
            "brandUrl": "apple.com",
            "name": "Apple"
        },
        "PLACEMENTS": {
            "categories": [
                {
                    "category": "Coupon",
                    "status": "ENABLED"
                },
                {
                    "category": "Email",
                    "status": "ENABLED"
                },
                {
                    "category": "Knowledge_Panel",
                    "status": "DISABLED"
                },
                {
                    "category": "Buy_Now_Pay_Later",
                    "status": "SELECTED_PLACEMENTS",
                    "bid": 2,5,
                    "placements": [
                        {
                            "placement": "Affirm",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Afterpay",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Clearpay",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Klarna",
                            "status": "ENABLED"
                        },
                        {
                            "placement": "Laybuy",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "PayWithFour",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Sezzle",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Wantlocker",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Zilch",
                            "status": "ENABLED"
                        },
                        {
                            "placement": "Zip",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Other",
                            "status": "DISABLED"
                        }
                    ]
                },
                {
                    "category": "Commerce_Content",
                    "status": "ENABLED",
                    "bid: 1.0
                },
                {
                    "category": "MSN",
                    "status": "DISABLED"
                },
                {
                    "category": "Browser_Autocomplete",
                    "status": "ENABLED"
                },
                {
                    "category": "Social",
                    "status": "DISABLED"
                },
                {
                    "category": "Tiles/Speed_Dial",
                    "status": "SELECTED_PLACEMENTS",
                    "placements": [
                        {
                            "placement": "Avast_and_AVG",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Huawei_and_Petal_Browsers",
                            "status": "ENABLED"
                        },
                        {
                            "placement": "Opera",
                            "status": "ENABLED"
                        },
                        {
                            "placement": "Smart_TV",
                            "status": "DISABLED"
                        },
                        {
                            "placement": "Other",
                            "status": "DISABLED"
                        }
                    ]
                },
                {
                    "category": "Ad_Network",
                    "status": "DISABLED"
                }
            ]
        }
    }
}

Endpoints

  1. Create - you can create a new campaign using this endpoint.
    • PUT https://panel.zeropark.com/api/v2/search-brand/campaigns
  2. Read - you can get details of your existing campaign using this endpoint, replacing {campaignId} with a proper ID.
    • GET https://panel.zeropark.com/api/v2/campaigns/{campaignId}
  3. Edit - you can edit your existing campaign using this endpoint. The campaign model must contain the ID section with the correct campaign ID.
    • PUT https://panel.zeropark.com/api/v2/search-brand/campaigns

Campaign Approval

Drive incremental
performance to
your brand

Sign up now