RTB API

Using merchenta.io for real-time bidding

Campaign model 

There are a vast array of campaign options available. The common settings are explained in more detail below.

Basic campaign settings

Path Required Type Description
code Y String The campaign code.

Must be unique and consist only of letters, numbers and hyphens. Once created, the campaign code will not change - it may be used as a primary key for further operations. Campaign codes must be prefixed with an advertiser code followed by hyphen (“-“).
advertiserDomain N String This is the URL of the advertiser (useful if the advertiser is different than the api user’s organization, ie agencies). It needs to be a valid URL preceded with http:// or https:// .
creatives Y Array Campaign creatives
status N String This is a read-only field that indicates the status of the campaign:

ACTIVE: Approved to run. Running.
INACTIVE: Approved to run. Paused.
PENDING: Campaign is under review.
REJECTED: Campaign was not accepted.
biddingSettings Y Object Bidding settings
timeSettings Y Object Time settings
targetingSettings N Object Targeting settings
inventorySettings Y Object Inventory settings
optimisationSettings N Object Optimisation settings
productSettings N Object Product settings

Creatives

Path Required Type Description
creatives[n] Y Object The creative object.
creatives[n] / code Y String The creative code.

Creative codes can be a maximum of 32 characters long and may only contain characters A to Z, a to z, 0 to 9 and hyphen (“-“). Creative codes must be prefixed with a campaign code followed by hyphen (“-“).
creatives[n] / status Y String An indicator of creative status.

It may be one of the following:
ACTIVE : Approved to run on one or more exchanges/publishers - reach may vary in accordance with publisher policies. Running.
INACTIVE : Approved to run on one or more exchanges/publishers - reach may vary in accordance with publisher policies. Paused.
PENDING : creative is under review.
REJECTED : creative was not accepted in accordance with creative standards or contains content prohibited by policy.
creatives[n] / type Y String This determines the type of creative.

It may be one of the following:
IMAGE : for static creative (eg JPEG/GIF/PNG)
FLASH : for Flash Player v8+ ads
FB_SIDEBAR : for Facebook sidebar ads
HTML-URL : for 3rd party hosted ad creative
HTML-SCRIPT : for Merchenta hosted HTML ad creative
INTELLIAD : for Merchenta Intelliads

All creative must comply with our supported ad formats.
creatives[n] / creativeId Y String (IMAGE, FLASH, FB_SIDEBAR, HTML-SCRIPT, VAST, VPAID)
The identifier for the creative previously uploaded.

(HTML-URL)
URL of 3rd party hosted ad creative.

(INTELLIAD)
intelliad11.swf
creatives[n] / alternateCreativeId N String The creative identifier for the alternate creative file.

This file will be used to render an ad in case the user’s browser does not support Flash and the primary creative is SWF/Flash. If no alternate creative is defined this field should not be set.
creatives[n] / dimensions Y Object Ad dimensions.

This should match the ad creative uploaded - for example “728x90” for an IAB standard leaderboard. All dimensions must comply with our supported ad formats.
creatives[n] / dimensions / width Y Number Ad dimensions - width
creatives[n] / dimensions / height Y Number Ad dimensions - height
creatives[n] / dimensions / expansion N Object Ad expansion settings
creatives[n] / dimensions / expansion / width Y Number Expanded ad width.
creatives[n] / dimensions / expansion / height Y Number Expanded ad height.
creatives[n] / dimensions / expansion / direction Y String Expanding direction.

Allowed values are:
UP
DOWN
LEFT
RIGHT
creatives[n] / clickthroughUrl Y String This is the URL (http or https) that the browser is redirected to when a consumer clicks an ad. For Flash-based creative, remember to ensure that a valid ClickTag handler is embedded within the ad creative. Clickthrough URLs must be at least 13 characters excluding transport prefix.
creatives[n] / postImpressionUrl N String This is the URL (http or https) that will be fired when an ad is displayed to consumer. If this is not specified, delivering an ad results in no impression tracking.
creatives[n] / facebook N Object Facebook creative metadata. Required only for FB_SIDEBAR type.
creatives[n] / facebook / title N String Facebook ad title
creatives[n] / facebook / body N String Facebook ad body
creatives[n] / intelliad N Object IntelliAd creative metadata. Required only for INTELLIAD type.
creatives[n] / intelliad / xml N String IntelliAd XML.
creatives[n] / webmCreativeId N String Required for VAST and VPAID creatives
creatives[n] / videoDuration N String Required for VAST and VPAID creatives in format “00:01:15”
creatives[n] / videoBitrate N String Required for VAST and VPAID creatives in kbps
creatives[n] / vpaidJsLocation N String Required for VPAID creatives
creatives[n] / vpaidJsParameters N String Required for VPAID creatives

Bidding settings

Path Required Type Description
biddingSettings / biddingStrategy Y Object One of bidding strategies
biddingSettings / pacingType Y String Pacing determines how quickly the campaign impressions are delivered within the constraints of the campaign settings themselves.

There are two options:
ACCELERATED - bid on all available impressions
PROPORTIONAL - bid evenly throughout the day on available impressions in proportion to the impressions available at that moment in time.
biddingSettings / maxBidsPerSecond N Number Numeric value describing how many bids can be made in one second. Since Merchenta has such a vast array of available inventory, this can be useful for low budget (< $10 per day) campaigns to prevent over-bidding. The setting is optional, in which case the default platform value (5 bps) will be used.
biddingSettings / budget Y Object The budget settings
biddingSettings / budget / daily Y* Number The budget for the campaign on a daily basis. Either a daily budget or a lifetime budget must be given..

Do not set if you want to specify a lifetime budget instead.
biddingSettings / budget / lifetime Y* Number The total budget for the campaign across its flight dates. Either a daily budget or a lifetime budget must be given..

Do not set if you want to specify a daily budget instead.

For example, if you set a lifetime budget of $14k for a campaign with flight dates spanning 7 days, the platform will deliver budget evenly at the rate of (lifetime budget / number of days in flight) - in this case, $2k per day.
biddingSettings / budget / currency N String The budget currency. If not set defaults to USD. Currency codes follow the ISO standard - for example US Dollar is USD, Euro is EUR.
biddingSettings / frequencyCap N Number Each campaign may have its own frequency cap (maximum number of impressions per consumer per 24 hour period). Merchenta operates universal frequency capping across all inventory sources. Where campaign-level settings are not provided (or are null), the advertiser level frequency cap associated with your account is used instead.

Bidding strategies

Path Required Type Description
.. / biddingStrategy / strategy Y String Strategy name.

Possible values are:
CPMCappedBiddingStrategy
CPMVariableBiddingStrategy
CPMZeroBiddingStrategy
CPMOneCentBiddingStrategy
CPCTargetBiddingStrategy
CTROptimisingBiddingStrategy
CPMFixedCPMBiddingStrategy
CPMFixedCPMPIDBiddingStrategy

For details of additional bidding strategies that may apply to your account, please contact your Account Manager.

CTROptimisingBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CTROptimisingBiddingStrategy. This bidding algorithm uses advanced machine learning techniques to automatically optimise campaigns to inventory that delivers a higher clickthrough rate. It encompasses over 800 features to select the best performing inventory for a given campaign, focussed upon providing CTR lift.
.. / biddingStrategy / defaultBid Y Number A based bid value that will be varied by bidding algorithm to hit the goal CTR.

CPCTargetBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CPCTargetBiddingStrategy
.. / biddingStrategy / goal Y Number CPC goal expressed as a cost-per-click in campaign currency. For example, if campaign currency was USD and we sought a 60 cent cost-per-click-target, this would be set to “0.60”.

CPMCappedBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CPMCappedBiddingStrategy
.. / biddingStrategy / maxBid Y Number Max CPM bid value expressed in campaign currency. This strategy will bid up to the CPM value specified but no higher. On a second price auction basis, generally the winning bid price is lower than this CPM so it can be seen as a CPM ceiling.

CPMVariableBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CPMVariableBiddingStrategy
.. / biddingStrategy / defaultBid Y Number Default CPM bid value expressed in campaign currency (eg “2.0” for $2/cpm). This strategy will vary bids around the default bid specified by +/- 10%.

CPMFixedCPMBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CPMFixedCPMBiddingStrategy
.. / biddingStrategy / goal Y Number The target fixed CPM bid value expressed in campaign currency. Real-time media markets work on an auction basis, which makes it difficult to deliver a fixed-price CPM for campaigns, as the clearing CPM will move around considerably in response to bid density, win rates and other factors within the second price auction environment. This bidding strategy interacts with the auction dynamics to tune bidding automatically to deliver campaign impressions as close to the target fixed CPM as possible.

CPMFixedCPMPIDBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CPMFixedCPMPIDBiddingStrategy
.. / biddingStrategy / goal Y Number The target fixed CPM bid value expressed in campaign currency. Real-time media markets work on an auction basis, which makes it difficult to deliver a fixed-price CPM for campaigns, as the clearing CPM will move around considerably in response to bid density, win rates and other factors within the second price auction environment. This bidding strategy uses a proportional, integrative and derivative function (hence the name “PID”) to dynamically adjust bids within the auction environment to target the fixed CPM specified. The approach is analagous to a heating thermostat where the temperature (in this case fixed CPM) is set and the device adjusts temperature around that value (in our case to deliver the fixed CPM target).

CPMZeroBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CPMZeroBiddingStrategy. This strategy is useful for testing purposes as it will consistently bid 0 price in campaign currency - no media will be bought.

CPMOneCentBiddingStrategy

Path Required Type Description
.. / biddingStrategy / strategy Y String CPMOneCentBiddingStrategy. This strategy is useful for testing purposes as it will consistently bid 0.01 (one cent) price in campaign currency - some media may be bought at these levels but on a second price auction basis winning bids are 1 cent lower than the highest bid so any cleared bids will be at 0 cost.

Time settings

Path Required Type Description
timeSettings / start N String A datetime in YYYY-MM-DDThh:mm:ss format indicating the start date/time for the campaign. All platform times are in UTC (universal timezone).
timeSettings / end N String A datetime in YYYY-MM-DDThh:mm:ss format indicating the end date/time for the campaign. All platform times are in UTC (universal timezone).
timeSettings / activeWindow N Array Each campaign may have one or more windows of activity which govern the days and times of day when the campaign is active. This works in conjunction with the flights dates (start/end datetime). If not set the campaign is active 24 hours Monday to Sunday.
timeSettings / activeWindow[n] Y Object Window object
timeSettings / activeWindow[n] / start Y String Window start time in hh:mm format
timeSettings / activeWindow[n] / end Y String Window end time in hh:mm format
timeSettings / activeWindow[n] / days N Array Window active days array.
If not set window will be active Monday to Sunday
timeSettings / activeWindow[n] / days[n] N String Window active day.

Valid values are:
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday

Targeting settings

Path Required Type Description
targetingSettings / geoSettings N Object Geo targeting options.

A vast array of geography related targeting options, including country, city/town, zipcode/postcode, latitude/longitude, DMA and place/radius targeting.
targetingSettings / contextualSettings N Object Contextual targeting.

Target publisher sites & content by contextual category.
targetingSettings / thirdPartySegments N Array DMP (3rd party) targeting.

Third-party data segments (eg demographic, behavioural data sourced from other websites) you wish to buy for use in the campaign.
targetingSettings / retargetingSettings N Object Retargeting.

A full range of retargeting options.
targetingSettings / deviceTargetingSettings N Object Device targeting.

For device targeting, including device family (tablet, desktop, mobile) plus browser, operating system and physical device.
targetingSettings / mobileOperators N Array Mobile operators targeting settings.
targetingSettings / ipWhitelists N Array Ip whitelists targeting settings.

Geo settings

Path Required Type Description
.. / geoSettings / countries N Array Array of strings containing the 2 character ISO country codes where the campaign should run. For example, [“GB”,”FR”,”US”] would run the campaign in United Kingdom, France & USA.
.. / geoSettings / countries[n] Y String 2 character ISO country code
.. / geoSettings / coordinates N Array Each campaign may have defined a set of geo coordinates along with radiuses (expressed in miles) to target inventory only from defined areas.
.. / geoSettings / coordinates[n] N Object Geo-coordinates targeting object
.. / geoSettings / coordinates[n] / latitude Y Number Latitude
.. / geoSettings / coordinates[n] / longitude Y Number Longitude
.. / geoSettings / coordinates[n] / radius Y Number Targeting radius in miles. Care should be taken to ensure that the radius is sufficiently large to capture a reasonable number of online consumers.
.. / geoSettings / cities N Array Each campaign may have defined a set of towns/cities (and country codes) coordinates along with radiuses (expressed in miles) to target inventory only from defined areas in and around those conurbations.
.. / geoSettings / cities[n] Y Object City targeting object.
.. / geoSettings / cities[n] / city Y String City/town name.
.. / geoSettings / cities[n] / countryCode Y String Since there are many towns/cities worldwide with the same name (eg Manchester, USA and Manchester,UK) the town or city should also be specified with the ISO country code. For instance, the UK country code is “GB”.
.. / geoSettings / cities[n] / radius N Number Targeting radius in miles. Care should be taken to ensure that the radius is sufficiently large to capture a reasonable number of online consumers.
.. / geoSettings / states N Array Array of USA state codes specifying the USA state codes for targeting for the campaign. Used only if countries contains “US”.
.. / geoSettings / states[n] Y String USA state code
.. / geoSettings / zipCodes N Array Array of USA zip codes specifying the USA zip codes for targeting for the campaign. Used only if countries contains “US”.
.. / geoSettings / zipCodes[n] Y String USA zip code
.. / geoSettings / dmaCodes N Array Array of DMA codes specifying the USA DMA codes for targeting for the campaign. Used only if countries contains “US”.
.. / geoSettings / dmaCodes[n] Y String USA DMA code

Contextual settings

Path Required Type Description
.. / contextualSettings / iabCategories N Array Contextual categories are defined as a series of identifiers (each of which maps to a category). Several categories may be specified.
.. / contextualSettings / iabCategories[n] Y Number Contextual category ID

Third party segments

Path Required Type Description
.. / thirdPartySegments[n] Y Object Segments may be used to target online consumers using third party data sources. To use a segment, specify the segment type and the associated segment identifiers.
.. / thirdPartySegments[n] / segmentType Y String Segment type. Presently, one segment type (third-party source) is supported - VISUALDNA.
.. / thirdPartySegments[n] / ids Y Array The segment identifiers are the VisualDNA “internal” segment identifiers.
.. / thirdPartySegments[n] / ids[n] Y String VisualDNA “internal” segment identifier.

Retargeting settings

Getting Started

Before configuring a campaign to use first-party audience segments for retargeting, one or more segments must be deployed. When these segments are triggered, the consumer is placed in the corresponding audience segment. Once the segment is populated with a reasonable number of people (eg >1000 people), it’s possible to use the segment in a campaign for (re)targeting purposes.

There are several types of segment available and we provide a segmentling API to create & manage audience segments.

Path Required Type Description
.. / retargetingSettings / startAfterVisitsInHour Y Number This setting determines the number of hours after a site visit that a consumer falls within a retargeting segment.
.. / retargetingSettings / lookBackWindowInDays Y Number This setting determines which consumers fall within the retargeting segment by including those website visitors who have visited the website within NN days of now. This option is expressed in whole days. If set, the campaign will retarget users who visited the advertiser’s site previously. Note that before enabling this option you should check with your Account Manager the segmentling/tagging procedure and correct instructions prior to use.
.. / retargetingSettings / firstPartySegments Y String This is the expression used for audience targeting - if an expression is set, Merchenta will use it for audience targeting/retargeting.

Creating Custom Audience Targeting Rules

A wide range of expressions are supported using a BOOLEAN-type notation. These enable simple targeting strategies (eg “target people who have opened email X”) through to more sophisticated approaches (eg “target people who opened email X AND clicked on a link AND who viewed one or more products in past 7 days AND who have NOT purchased anything within 2 days”). Note : Segmnets expressions are case sensitive.

Some examples:

segment123

User belongs to segment “segment123” - the date the user joined the segment is irrelevant

segment123[7]

User joined segment “segment123” within the past 7 days

segment123[7] AND segment456[3]

User joined segment “segment123” within the past 7 days and they also joined segment “segment456” within the past 3 days

segment123[3] AND segment456[3] AND segment789[3] AND segment000[3]

User joined three segments within the past 3 days - segment “segment123”, segment “segment456” and “segment1000”.

segment123[7] OR segment456[3]

User joined segment “segment123” in the last 7 days or segment “segment456” in the last 3 days

NOT segment123

User is not a member of segment “segment123”.

NOT segment123 AND (segment465[7] OR segment789[7])

User does not belong to segment “segment123” and joined segment “segment465” or “segment789” within the last 7 days

segment123 AND segment465[7] OR segment789[7]

This is not valid expression, as it would confuse people - you have to use parentheses when combining AND and OR! The preferred format is to have one OR condition at the start of expression, then those segments which the user should have joined and finally, those segments which user isn’t a member of eg

(segment1 OR segment2) AND segment3 AND segment4 NOT segment5

Device targeting settings

Path Required Type Description
.. / deviceTargetingSettings / languages N Array Language targeting can be performed with reference to the languages supported by the consumer’s browser. This is more effective that targeting the language of the page hosting the ad placement.
.. / deviceTargetingSettings / languages[n] N String Language code in ISO 639-1 format.
.. / deviceTargetingSettings / devices N Array Array specifying the types of device to run the campaign across.
.. / deviceTargetingSettings / devices[n] N String Device type.

Valid values are :
DESKTOP
SLATE
MOBILE
CONSOLE
WEARABLE
TV
.. / deviceTargetingSettings / userAgentTargets N Array It’s also possible to target devices at a more granular level - using operating system (OS), browser or device type targeting.
.. / deviceTargetingSettings / userAgentTargets[n] N Object User agent target object.
.. / deviceTargetingSettings / userAgentTargets[n] / os N String Operating system family name
.. / deviceTargetingSettings / userAgentTargets[n] / osMajorVersion N String Operating system major version
.. / deviceTargetingSettings / userAgentTargets[n] / osMinorVersion N String Operating system minor version
.. / deviceTargetingSettings / userAgentTargets[n] / device N String Device family name
.. / deviceTargetingSettings / userAgentTargets[n] / userAgentFamily N String Browser family name
.. / deviceTargetingSettings / userAgentTargets[n] / userAgentMajorVersion N String Browser major version
.. / deviceTargetingSettings / userAgentTargets[n] / userAgentMinorVersion N String Browser minor version

Mobile operators

Path Required Type Description
.. / mobileOperators[n] Y String Mobile operator

IP Whitelists

Path Required Type Description
.. / ipWhitelists[n] Y String The item could be a single IP address (e.g. 127.132.43.30) or a range of IP addresses (e.g. 127.132.0.0-127.132.255.255).

Inventory settings

Path Required Type Description
inventorySettings / exchangeBlockList N Array Array of exchange codes to be blocked. This allows selection of exchanges on a per campaign basis - setting the value to null will ensure that campaigns run across all exchanges subject to the other campaign criteria.

Exchange inventory availability can vary by region, so for the widest reach, set this value to null. If you encounter error messages relating to “sensitive content”, be sure to check that that you are blocking GD and BS exchanges. Alternatively, contact your Account Manager to arrange a review of your account to enable this restriction to be lifted.

Exchange codes are set as follows :

AD - Adscale
AM - Admeta
AN - AppNexus
BS - BidSwitch
CL - Casale Media
CT - Pulsepoint
AE - Aerserv Exchange
FB - Facebook Exchange (FBX)
GD - Google Doubleclick
IM - Improve Digital
NX - Nexage
OX - OpenX
RB - Rubicon Project
TS - TapSense
SM - Smaato

To enquire about additional exchanges available - please contact your Account Manager.
inventorySettings / exchangeBlockList[n] Y String Exchange code to be blocked.
inventorySettings / placementType N Array Determines whether the campaign is run on placements above-the-fold (ATF), below-the-fold (BTF) or other placements (UNKNOWN). Settings can be combined, so to run above & below the fold select ATF and BTF.
inventorySettings / placementType[n] Y String Placement type.

Valid values are :
ATF - bid on above-fold placements
BTF - bid on below-fold placements
UNKNOWN - bid on placements where fold positioning is unclear or where a unit spans ATF & BTF
inventorySettings / inventoryType Y Array Determines whether the campaign is run on all available media or only pre-bid known sites.
inventorySettings / inventoryType[n] Y String Valid values are :

TRANSPARENT - bid on pre-bid identified sites
BLIND - bid on all media including transparent sites and sites where the site URL is unknown pre-bid
inventorySettings / publisherWhiteList N Array Array of site domains specifying the site list for the campaign. This can form the basis of a pre-targeting strategy.
inventorySettings / publisherWhiteList[n] Y String Valid domain.
inventorySettings / trafficType N Array Determines type of targeting traffic types. Currently, we support three type of traffic: Desktop web (WEB), mobile app (MOBILE_APP) and mobile web (MOBILE_WEB). Leaving this property empty if you want to target all traffic types.
inventorySettings / trafficType[n] Y String Valid traffic type (WEB, MOBILE_WEB or MOBILE_APP).

Optimisation settings

Settings to help auto-optimise campaigns.

Path Required Type Description
optimisationSettings / optimisationStrategy Y String An optimisation strategy can be used to influence the selection of campaigns within a campaign group (ie which ad creative is selected out of many associated with a campaign). This is an advanced setting and should be used with care.

It will only take effect if the campaign has more than 1 ad creative. By default, the platform will use a ROUND_ROBIN approach, which allocates impressions more-or-less evenly to creatives in line with incoming, matching bid request placements.

The possible options are :
ROUND_ROBIN : the default
CTR : allocate greater weight to creatives with the highest clickthrough rate
ETR : allocate greater weight to creatives with the highest engagement rate (note : IntelliAds only)
WIN_RATE : allocate greater weight to creatives with the highest win rate
CPM : allocate greater weight to creatives with the highest eCPM

If you specify and optimisationStrategy, you must also set the commenceOptimisationAfter setting.
optimisationSettings / commenceOptimisationAfter Y Number This setting determines the trigger point for the optimisationStrategy. To prevent premature optimisation, specify the number of impressions that must be served by the campaign before the optimisationStrategy kicks in.

If you specify an commenceOptimisationAfter, you must also set the optimisationStrategy setting.

Product settings

Path Required Type Description
productSettings / recommendationStrategy Y String Products recommendation strategy. This must be set if creative type is INTELLIAD.

Valid values are:
BestSellerRecommenderStrategy
RecentlyViewedProductsRecommenderStrategy
HybridAffinityRecommenderStrategy
GeoProximityRecommenderStrategy
RandomRecommenderStrategy
RecentlyViewedRecommenderStrategy
ContentBasedRecommenderStrategy
TictailRecentlyViewedProductsRecommenderStrategy
Next page  Previous page