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:

Realtime Statistics ¶

The realtime statistics endpoint shows the spend and clicks on a particular adgroup for the current day. It is important to note that while the data here is updated in realtime, the data in the rest of the dashboard (including reporting) is refreshed with about 4 hours of delay.

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 ¶

Upload Video Assets ¶

Video assets are uploaded on the account level and separately from the ads that will later use them. First you create a new video asset with a chosen method of upload. You can upload a video file or a VAST directly or you can provide a URL from which the VAST will be downloaded.

When uploading a video file directly, you need to upload it to the provided upload URL and then poll for the status as the video is processed asynchronously. Should any errors occur, the upload URL can be reused. When the status changes to READY_FOR_USE, the id of the video asset can be used as a videoAssetId when creating ads for a video campaign.

When uploading a VAST, the processing will trigger only when the first ad using this videoAssetId is uploaded.

When uploading a VAST using VAST_URL, the VAST will be downloaded, processed and and ready for use immediately.

Video Asset ¶

Video upload settings ¶