Zemanta API

Acquire a new authentication token ¶

Accounts ¶

Account Targeting Settings ¶

Account Credit ¶

After your Insertion Order for media spend has been executed Zemanta’s Customer Success team will assign a credit line to your account. With credit added to your account you have the ability to create budget items and associate them with the campaigns you’re planning.

Pixels ¶

Zemanta’s pixels allow you to report conversions, build audiences and get insights about how people use your website. Pixels need to be properly placed in order to measure goals effectively. We recommend placing your pixel on the confirmation page which is shown to a person after the desired action is performed.

Audiences ¶

Custom audiences allow you to target your ads to a specific set of people with whom you have already established a relationship. Audiences can be defined by a combination of rules used to identify users who took specific actions on your website.

Audience Rules ¶

Choose how you want to add people to your audience. Include all of your website visitors or create rules that only add people visiting specific parts of your website. Audience can have multiple rules set. CONTAINS and STARTS_WITH rules can match multiple values separated by a comma. STARTS_WITH values need to be valid URLs.

Campaigns ¶

A Campaign is a collection of Ad Groups. It holds common settings for all Ad Groups and also has budgets and goals associated.

Tracking Settings ¶

Postclick tracking integration can be set up for Google Analytics and Adobe Analytics.

Campaign Targeting Settings ¶

Campaign Budgets ¶

Each budget item is part of a Credit Item and allows a campaign to spend a portion of the credit.

A campaign needs at least one active budget associated with it before its Ad Groups can be started.

More info available here.

Campaign goals ¶

Campaign goals give Zemanta’s intelligent campaign automation feature Autopilot data to help optimize your campaign for optimal results.

A campaign needs at least one goal associated with it before any of its Ad Groups can be started.

Conversion Goals ¶

Ad Groups ¶

An Ad Group is a collection of Content Ads that has specific targeting settings.

Before any Ad Groups in the campaign can be activated, a campaign must have at least one active Budget and at least one Goal associated.

Targeting Settings ¶

Operating System Targeting Settings ¶

Dayparting ¶

Dayparting structure is defined as a dictionary of days which point to a list of hours that are enabled in that day, eg. “monday” -> [0, 1, 2, 5]. This means that on monday bidding is enabled from 00:00 to 02:59 and from 5:00 to 5:59. The other value is “timezone” that defines in which timezone the hours are evaluated, eg. “timezone” -> “America/New_York”. This value must be formatted according to the tz database (see https://en.wikipedia.org/wiki/Tz_database). If timezone isn’t specified then user’s timezone is used to resolve the hours.

Audience Targeting ¶

An Audience Targeting expression is an object containing a single property. The name of the property represents the operator, while its value is an array representing the subexpression(s). A subexpression can be either a nested Audience Targeting expression or a Category object.

Valid operators are AND, OR and NOT. NOT has to have exactly one nested subexpression in the child array.

Example Audience Targeting expression:

{
    "AND": [
        {
            "OR": [
                {
                    "category": "bluekai:839868"
                },
                {
                    "category": "bluekai:763921"
                }
            ]
        },
        {
            "NOT": [
                {
                    "category": "bluekai:839918"
                }
            ]
        }
    ]
}

Audience Targeting Category ¶

Audience targeting subexpressions can either be a nested audience targeting expressions or a leaf category node.

Currently the only supported provider is bluekai. See BlueKai Taxonomy API for a list of all available BlueKai categories.

Zemanta Autopilot Settings ¶

Get more information about Zemanta Autopilot in our knowledge base.

In order to set Autopilot state to ACTIVE_CPC_BUDGET all real-time bidding sources groupEnabled setting has to be set to true.

Ad Group Sources ¶

Each Ad Group has specific configurable settings for each media source. You can control whether the ad group is promoted on a given source, the CPC you are willing to pay on that source and the daily budget you wish to spend on that source.

All Real-time bidding sources as one ¶

The sources you can promote your content on come in two flavours: real-time bidding (RTB) and non-real-time bidding (Non-RTB) sources. RTB sources are all sources except yahoo (US clients only) and outbrain (deprecated, please use outbrainrtb).

In order to simplify manual source management (when not using Zemanta Autopilot), you can use this special RTB settings endpoint, which allows you to group all RTB sources together and treat them as a single source. This allows you to set the state and daily budget of all RTB sources at once. The daily budget set by this endpoint will be shared among all RTB sources. Daily budget for non-RTB sources must still be set through the Ad Group Sources endpoint.

This setting has to be enabled in order to be able to set autopilot state to ACTIVE_CPC_BUDGET.

Bid Modifiers ¶

Bid modifiers enable modifying the bidding price for an ad group according to the desired parameters. The modified CPC or CPM bid value is calculated in the following way: modifiedBidValue = bidValue * modifier. A bid request can match multiple bid modifiers with different types (for example DEVICE, OPERATING_SYSTEM and COUNTRY). In that case the modified bid value is calculated by multiplying all matching bid modifier values: modifiedBidValue = bidValue * modifier1 * modifier2 * modifier3. The allowed modifier values are limited to the interval between 0.01 and 11.0.

Bid Modifier Types ¶

The following bid modifier types are supported:

A note on SOURCE bid modifiers: API already supports SOURCE bid modifiers, but setting them currently has no effect in the system. Full support for SOURCE bid modifiers will be added shortly.

Upload Content Ads ¶

Content Ads are uploaded in batches. First, you create an upload batch with the Content Ads you want to upload. Then, you poll the status of the batch and the validation status of the individual Content Ads. If any of the Content Ads in the batch fail the validation process, none of the Content Ads in the batch will be accepted into the system.

If and when all the Content Ads in the batch pass the validation process, they are accepted into the system.

Content Ad ¶

Upload Batch ¶

Manage content ads ¶

Publisher Groups ¶

Publisher Groups are named collections of publishers that can be referenced in Ad Group’s publisherGroups targeting section as whitelists or blacklists. Publishers are represented as publisher domain (or name) and source pairs in the same manner as in publisher reports and blacklist management.

Publisher Groups Entries ¶