Salesforce

Ad API - POST method - Reference

« Go Back
Information
Ad API - POST method - Reference
Ad-API-reference
Details

In this article

Related articles

Overview

This article describes all parameters and objects of Equativ's HTTP POST Ad API. For general information about Equativ's Ad API, including samples, read Ad API - usage.

First-level parameters

These parameters are almost identical for both Generic POST and Onecall POST requests. The only difference is that the output parameter is available for Generic POST requests only..
 
Key__________________Type__________NecessityDescription
Placement related parameters
siteIdINTEGEROPTIONALthe site ID; represents a website, mobile application or a video player; read more about sites in Setting up inventory 
content_source_idINTEGEROPTIONALa custom ID that a publisher can pass in the ad request as an identifier for a sub-domain, blog, channel, page or any other piece of content; the field is available as a reporting dimension.
pageIdINTEGERREQUIREDthe page ID; child element of a website; represents a category/section on a website, in an app or in a video player; read more about pages in Setting up inventory
pageNameSTRINGOPTIONALthe page name; usage not recommended; can be used instead of pageId to identify the page; required if pageId is not provided; if pageName is used, siteId is required as well; usage available upon request only - please contact Equativ support
pageUrlSTRINGOPTIONALthe page URL; if used, it overrides the actual URL from which the ad request originates
Other parameters
addtl_consentSTRINGOPTIONALthe additional consent string (Google); more details in chapter “Google’s additional consent mode” in GDPR compliance - technical implementation
ads[]OBJECT ARRAYREQUIREDthe array of ad objects (see "Object: Ad" below)
appOBJECTOPTIONALthe app object will be available soon; in the meantime, see "In-app parameters" in Ad API - GET method
appNameSTRINGREQUIRED (for mobile in-app calls)the application name 
bundleIdSTRINGOPTIONALthe application bundle ID; has the form of a right-to-left domain name, e. g. com.my-app-name
doNotTrackIdSTRINGOPTIONALa user id that can be used if cookies cannot be dropped in user’s browser (e. g. for frequency capping).
dsaOBJECTOPTIONALsee chapter "Object: Dsa" below
eids[].sourceSTRINGOPTIONALthe user identification provider that provides the uids (see eids[].uids[] below); more details in Extended User Identification
eids[].uids[]OBJECT ARRAYOPTIONALthe array of uid objects (see chapter "Object: Uid" below) provided by the user identification provider (see eids[].source above); usually only one element is provided; more details in Extended User Identification
gdprBOOLEANOPTIONALindicates if the given request is from a location where the GDPR applies; if not provided, Equativ will attempt to leverage the geolocation of the user to determine if the GDPR applies; "0" if the GDPR does not apply; "1" if the GDPR applies; more details about GDPR in Global Privacy Platform (GPP)
gdpr_consentSTRINGREQUIRED (for EU traffic)the encoded GDPR consent string, as defined by the IAB Transparency & Consent Framework.
Note: If the gdpr parameter is set to "1", gdpr_consent becomes mandatory; more details about GDPR in  Global Privacy Platform (GPP)
geolocation.
latitude
DOUBLEOPTIONALthe latitude of the device
geolocation.
longitude
DOUBLEOPTIONALthe longitude of the device
getAdContentBOOLEANOPTIONALif true, insertions are resolved and ads are displayed at the first call, without using nshow URLs; used only for Onecall
gppSTRINGOPTIONALthe Global Privacy Platform (GPP) consent string
gpp_sidINTEGER ARRAYOPTIONALan array of the section(s) of the GPP string to be applied for this transaction; generally, will contain one and only one value; more than one may apply in rare cases; see list of section IDs
iabframeworksSTRINGOPTIONALthe supported IAB API frameworks for the given impression:
  • 1 - VPAID 1.0
  • 2 - VPAID 2.0
  • 3 - MRAID-1
  • 4 - ORMMA
  • 5 - MRAID-2
  • 6 - MRAID-3
  • 7 - OMSDK
separate multiple values by a comma (e. g. iabframeworks=1,2,7)
inventoryPartnerDomainSTRINGOPTIONALthe inventory partner domain to designate a domain of an inventory sharing partner for purposes of ads.txt/app-ads.txt validation (see IAB specification)
masterSTRINGOPTIONAL
  • m - master request; indicates that the request should be counted as a page impression; use m only for the first request from a given page; all subsequent requests from the same page should use s
  • s - slave request; indicates that the request should be counted as a regular ad impression; do not use s for the first request from a given page;
  • parameter is optional; if absent, the default value is used: m (master) in case of Onecall or s (slave) in case of standard call
mraidVersionSTRINGOPTIONALthe mraid version; allowed values: 1.x.x or 2.x.x
only the major version number will be taken into consideration; at least one minor version number is mandatory;
e. g.: 1.6 or 2.4 are allowed but 1 or 2 are not allowed
networkIdINTEGERREQUIREDthe network ID; identifies the network (Equativ customer’s workspace); see chapter “Authentication” here for more details
noAdCallbackSTRINGOPTIONALthe callback used when ad response is empty (“noad”); used only when output is set to javascript
noCookieBOOLEANOPTIONALif true, the insertions where the option “Limit delivering of this insertion to browsers that accept cookies” is enabled, will not deliver (more about this option in Insertions: General settings)
omidpnSTRINGREQUIRED (if iabframeworks=7 is sent)s“Open Measurement Interface Definition partner name”; specifies the identifier of the OM SDK integration; this is the same as the name parameter of the OMID Partner object; Equativ sends omidpn in the bid request only if iabframeworks=7 is sent in the ad request
omidpvSTRINGOPTIONAL“Open Measurement Interface Definition partner version”; specifies the version of the OM SDK integration; this is the same as the versionString parameter of the OMID Partner object; Equativ sends omidpv in the bid request only if iabframeworks=7 is sent in the ad request; omidpv cannot be sent without any omidpn value
outputSTRINGOPTIONALused in Generic POST requests only; requests a specific type of response; values can be either literal (e. g. js) or value (e. g. 1) :
  • Javascript: js or 1
  • Nonrich: nonrich or 2
  • Iframe: iframe or 4
  • XML: xml or 8
  • JSON: json or 16
  • VAST: vast or 32 (calls a VAST ad with version 4.0 or lower; read about calling specific VAST ad versions below)
Calling specific VAST ad versions:
  • vast4.2 - calls a VAST ad with version 4.2 or lower
  • vast4.1 - calls a VAST ad with version 4.1 or lower
  • vast4 or vast or 32 - calls a VAST ad with version 4.0 or lower
  • vast3 - calls a VAST ad with version 3.0 or lower
  • vast2 - calls a VAST ad with version 2.0
overridden
Currency
STRINGOPTIONALthe ISO currency code (EUR, USD etc.); if used, overrides the network currency for CPM related macros in script templates
partnerExtUidsDICTIONARY <STRING,STRING>OPTIONALthe dictionary partner id; user id that can be used in addition to csync cookie
pidSTRINGOPTIONALEquativ’s proprietary user identifier; used to ensure appropriate user synching with partners; optional but strongly recommended in case of Ad API integrations where there is no way to access cookies in users' browsers
schainSTRINGOPTIONALthe SupplyChain Object parameter; lists all parties who are selling or reselling the ad; each party is represented by a SupplyChain Object node; e.g.:
"1.0,1!exchange1.com,1234,1,publisher,publisher.com"
screen.heightINTEGEROPTIONALthe height of the screen
screen.widthINTEGEROPTIONALthe width of the screen
sdaOBJECT ARRAYOPTIONALan object containing additional user data; used for Seller Defined Audience data; corresponds to the user.data object in open RTB integrations
sdcOBJECT ARRAYOPTIONALan object containing additional content data; used for Seller Defined Context data; corresponds to the site.content.data object in open RTB integrations
sibBOOLEANOPTIONALindicates if the request is used in the context of in-app header bidding or not
srlSTRINGOPTIONALthe store URL of a connected TV / mobile application; if missing in the ad request, Equativ will build and pass the store URL through an automated fallback mechanism; however, this mechanism is applied only in case the store URL is missing in the ad request (no overriding of erroneous store URLs through this mechanism!)
timestampLONGOPTIONALa random number mainly used for cache busting purposes
uidSTRINGOPTIONALa unique identifier for the user that can be used instead of Equativ’s pid
us_privacySTRINGOPTIONALthe CCPA (California Consumer Privacy Act) consent string; more details in: California Consumer Privacy Act (CCPA) implementation
videoOBJECTOPTIONALsee chapter "Object: Video" below

Objects

Object: Ad

An Ad object represents a format (ad slot, e. g. Medium rectangle) on a page with its individual configuration. 
Key_________________Type________Necessity____Description
bidfloorFLOATOPTIONALthe minimum bid price for this ad in the network currency; e.g: 0.23
formatIdINTEGERREQUIREDthe format ID; represents an ad slot on a page or in an app (e. g. medium rectangle); read more about formats in Setting up inventory
headerBiddingOBJECTOPTIONALsee "Object: Header bidding" below
isLazyBOOLEANOPTIONALindicates if the format is called using lazy loading, i. e. the format is only called if the user scrolls to the location of the format - typically at the end of the page; more about lazy loading here
tagIdSTRINGOPTIONALthe DOM tagId where the ad will be rendered; by default, the tagId name follows the pattern: sas_<format id>. For instance, if the format id is 12345, the associated tagId is: sas_12345.
In case of OneCall POST requests, make sure you add a dedicated tagid to each format. If the same tagid is reused for multiple formats, only the first format in the OneCall request will be taken into account. Using the format id as part of the tagId (like in the default tagId naming pattern  sas_<format id>) is strongly recommended.  
targetSTRINGOPTIONALthe key=value targeting of the ad (e.g: gender=male);
In case of multiple keywords or key=values, use a semicolon (;) to separate them (e.g. color=green;color=red;sport;football).
The comma character (,) must never be used as a separator because this character will be considered as part of the key=value or keyword itself.
Read more in Keyword targeting
 

Object: Video

With the Video object you can call instream video ads (e. g. prerolls). For an ad request to be processed as a video ad request, a video object must be declared and the output must be set to vast or a specific VAST ad version (see output parameter in table "First-level parameters" above ).
 
Warnings
  • Do not use the Onecall POST request to deliver instream video ads. Instead, use the Generic POST request. A Onecall request enforces JSON output, so the request is not processed as an instream video request.
  • Do not add the network Id to the instream video request.
Key___________Type_________NecessityDescription
abINTEGERREQUIREDthe ad break; possible values:
  • 0 - default
  • 1 - preroll
  • 2 - midroll
  • 3 - postroll
  • Not set for overlays
default value: 1
abposINTEGEROPTIONALlogs the ad break position (PositionInAdBreak); e.g. a value of 2 is logged if the ad has been played in the 2nd position in an ad break of 5 ads
aridINTEGEROPTIONALthe ad rule id (VideoAdRuleId);
logs the application of server side ad rules when Equativ returned the video ad;
possible values:
  • VideoAdRuleId=-1 means that a client side ad rule was applied; i. e. the video ad was served without any involvement of server side ad rules
  • VideoAdRuleId=0 means that server side ad rules were applied but none of them was matching
  • VideoAdRuleId=[Id] indicates that a server side ad rule was matching and was applied; [Id] represents the Id of the actual ad rule that was applied (as set up in EMP)
ctcSTRINGOPTIONALthe video content category; supports one or multiple values; multiple values must be separated by a comma – e. g.: ctc=cat1,cat2,cat3; Key name in Video plugin*: sas_videoContentCategory; Macro name: [sas_videoContentCategory]
ctchSTRINGOPTIONALthe name of the content channel; Key name in Video plugin*: sas_videoContentChannelName 
ctdSTRINGOPTIONALthe video content duration in seconds; the value -1 indicates a live stream; Key name in Video plugin*: sas_videoContentDuration; Macro name: [sas_videoContentDuration]
ctdidSTRINGOPTIONALthe video content distributor Id; Key name in Video plugin*: sas_videoContentDistributorId; Macro name: [sas_videoContentDistributorId]
ctdnSTRINGOPTIONALthe video content distributor name; Key name in Video plugin*: sas_videoContentDistributorName; Macro name: [sas_videoContentDistributorName]
cteSTRINGOPTIONALthe episode number of the content; format ISO-639-1-Alpha-2 is strongly recommended; Key name in Video plugin*: sas_videoEpisodeNumber; Macro name: [sas_videoEpisodeNumber]
ctgrSTRINGOPTIONALthe genre describing the content (e. g. "Rock", "Pop")
ctidSTRINGOPTIONALthe video content Id to uniquely identify the content; used for syndication purposes; Key name in Video plugin*: sas_contentid; Macro name: [sas_contentid]
ctkSTRINGOPTIONALone or multiple keywords (tags) that describe the video content (separated by comma); Key name in Video plugin*: sas_videoContentTags; Macro name: [sas_videoContentTags]
ctlgSTRINGOPTIONALthe language of the content; format ISO-639-1-Alpha-2 is strongly recommended
ctmsidSTRINGOPTIONALthe content management system Id in charge of the video content; Key name in Video plugin*: sas_videoCmsId; Macro name: [sas_videoCmsId]
ctnSTRINGOPTIONALthe video content name (title); Key name in Video plugin*: sas_contentTitle; Macro name: [sas_contentTitle]
ctnwSTRINGOPTIONALthe name of the content network; Key name in Video plugin*: sas_videoContentNetworkName 
ctpSTRINGOPTIONALthe video content provider name; Key name in Video plugin*: sas_contentProviderName; Macro name: [sas_contentProviderName]
ctpidSTRINGOPTIONALthe video content provider ID; used for syndication purposes; Key name in Video plugin*: sas_contentproviderid; Macro name: [sas_contentproviderid]
ctrSTRINGOPTIONALthe permissible audience of the video content (general audiences, parental guidance, adult, etc.); supports one or multiple values; multiple values of a key must be separated by a comma; Key name in Video plugin*: sas_videoContentRating; Macro name: [sas_videoContentRating]
ctsSTRINGOPTIONALthe video content season number; Key name in Video plugin*: sas_videoSeasonNumber; Macro name: [sas_videoSeasonNumber]
cttSTRINGOPTIONALthe video content type; supports one or multiple values; multiple values must be separated by a comma; Key name in Video plugin*: sas_videoContentType; Macro name: [sas_videoContentType]
ctxidSTRINGOPTIONALthe video content id in an external (3rd party) system; Key name in Video plugin*: sas_externalContentId; Macro name: [sas_externalContentId]
ecINTEGEROPTIONALlogs the video error code, if an error occurred; more about video error codes with a complete list here
liveBOOLEANOPTIONALdefault value: 0; indicates if the ad request is originating from an ad break in a live video stream (live event) or not; live video streams generate traffic peaks during ad breaks (many simultaneous ad requests); live=1 ensures appropriate ad delivery pacing during such ad breaks
mabdSTRINGOPTIONALthe maximum adbreak duration; sets a duration limit for the ad pod (in seconds)
pbINTEGEROPTIONALthe number of passback ads; defines the number of additional ads to be delivered with the VAST response for failover (fallback) purposes (see "ad buffet" in the VAST specification);
default (if pb is not specified): 4 passback ads, if available on the placement; a maximum of 10 passback ads can be served;
pb=0 disables passback ads entirely
Keep in mind: Only insertions without any video ad pod position targeting can be served as passback ads; read here for more on video ad pod position targeting
psINTEGEROPTIONALthe ad pod size; specifies the number of sequenced ads to be returned in the VAST ad response, default value: 1
skipBOOLEANOPTIONAL

declares a video as being skippable or not in the bid request

ssarBOOLEANOPTIONALdetermines which video ad rules should be applied;
  • ssar=0 deactivates server side ad rules and activates client side ad rules
  • ssar=1 activates server side ad rules and deactivates client side ad rules
vbrmaxINTEGEROPTIONALthe maximum bitrate of the video creative served programmatically, in Kbps; must have a positive value
vbrminINTEGEROPTIONALthe minimum bitrate of the video creative served programmatically, in Kbps; must have a positive value
vcnSTRINGOPTIONALa boolean indicating if noad is counted client-side or server-side; noad occurs when more ads are requested than available on the placement;  noad counting is done for reporting and forecasting purposes; The server side counting method (vcn=s) means that Equativ counts empty (unmonetized) inventory server side. Empty inventory occurs when the number of ads returned by Equativ is less than the number of ads requested by the pod size (ps=) parameter or by the maximum ad break duration (mabd=) parameter in the VAST request. Empty inventory is counted with the report metric "No ad".

Keep in mind: In case of client side counting, missing ads should be counted on the client side as described in “Counting empty inventory in case of standalone VAST requests” below.
vctINTEGEROPTIONALthe video client technology Id passed by Equativ's video plugin; possible values:
  • 1 - Flash (deprecated)
  • 2 - javascript
vdSTRINGOPTIONALlogs the video ad duration in seconds
vdmaxINTEGEROPTIONALthe maximum duration of the video creative served programmatically, in seconds; must have a positive value; default value: 60
vdminINTEGEROPTIONALthe minimum duration of the video creative served programmatically, in seconds; must have a positive value, greater than or equal to 1; default value: 1
vitINTEGEROPTIONALthe video integration type passed by Equativ’s video plugin; possible values:
  • 1 - Instream Plugins
  • 2 - Instream Embedded Ad Manager
  • 3 - Outstream synchronous formats (obsolete)
  • 4 - Outstream asynchronous formats
  • 5 - Server side ad insertion (SSAI)
vpaidtSTRINGOPTIONALthe VPAID type;
vpaidt=js requests the VPAID type javascript
vpaidvINTEGEROPTIONALthe VPAID version;
  • 0 - VPAID not supported (mandatory if VPAID is not supported at all)
  • 1 - VPAID version 1
  • 2 - VPAID version 2
  • 1,2 - both VPAID versions in a single request
vphINTEGEROPTIONALthe video player height, in pixels
vplcmtINTEGEROPTIONALthe video placement type in accordance with updated IAB Digital Video Guidelines; replaces vpt parameter; definitions below are shortened - for full definitions, see List: Plcmt Subtypes - Video 
  • 1 - Instream; pre-roll, mid-roll and post-roll ads played before, during or after the streaming video content requested by user; must be sound-on by default at player start
  • 2 -  Accompanying Content; pre-roll, mid-roll and post-roll ads played before, during, or after streaming video content; video player loads and plays before, between, or after paragraphs of text or graphical content and starts playing only when it enters the viewport.
  • 3 - Interstitial; video ads played without video content; must be primary focus of the page and take up the majority of the viewport; cannot be scrolled out of view; can be placements like in-app video or slideshows.
  • 4 - No Content/Standalone; video ads played without streaming video content; can be placements like slideshows, native feeds, in-content or sticky/floating
vpmtINTEGEROPTIONALthe video playback method; set to -1 by default (feature disabled):
  • -1: Default value, disables the feature
  • 1: Initiates on Page Load with Sound On
  • 2: Initiates on Page Load with Sound Off by Default
  • 3: Initiates on Click with Sound On
  • 4: Initiates on Mouse-Over with Sound On
  • 5: Initiates on Entering Viewport with Sound On
  • 6: Initiates on Entering Viewport with Sound Off by Default
vptINTEGEROPTIONALthe video placement type; deprecated as of open RTB 2.6-202303 release; for the latest types of video placements in accordance with updated IAB Digital Video Guidelines, see vplcmt parameter above
  • 1 - In-Stream; played before, during or after the streaming video content;
  • 2 - In-Banner; exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format; the format relies on the existence of display ad inventory on the page for its delivery;
  • 3 - In-Article; loads and plays dynamically between paragraphs of editorial content;
  • 4 - In-Feed; in content, social or product feeds;
  • 5 - Interstitial / Slider / Floating; covers the entire or a portion of the screen area, but is always on screen while displayed (i.e. cannot be scrolled out of view).
vpvaSTRINGOPTIONALlogs the area of the video ad that was viewed, in percent (VideoPercentageViewedArea
vpwINTEGEROPTIONALthe video player width, in pixels
vrnSTRINGOPTIONALthe git revision number of the library used by the client
Key name in Video plugin: the key name in the contentData object when the used integration method is the Video plugin (documentation here)

Object: App

The app object does not exist yet but will be available soon. In the meantime, use the GET Ad API (see chapter: "In-app parameters").

Object: Header bidding

The header bidding object is used in the context of Equativ's holistic+ integration: the parameters of the prebid.js header auction winner (for a given format) are passed to Equativ using the header bidding object. Equativ will then leverage these parameters in its Holistic+ competition, i. e. competition between the header auction winner, bids from Equativ’s demand partners and direct campaigns. 
Keep in mind that the Generic POST or Onecall POST request types must be used in case of the Holistic+ integration. 
Key______________Type_______Necessity____Description
bidderSTRINGREQUIREDthe name of the bidder that won the header auction
cpmDECIMALREQUIREDthe header auction winner’s bid price; this price will be used as a floor price when Equativ requests bids from demand partners; e.g: 0.23
currencySTRINGOPTIONALthe currency of the header auction winner’s bid price, expressed as an ISO 4217 3-letter currency code; e.g.: EUR
dealIdSTRINGOPTIONALthe ID of the deal associated with this ad opportunity

Object: Uid

The uid object is used to pass a user id provided by a user identification provider; see eids[].source and eids[].uids[] in chapter "First-level parameters" above; more details also available in Extended User Identification;
Key________Type_________Necessity___Description
atypeINTEGEROPTIONALthe agent type the ID is coming from:
  • 1 - Web; an ID which is tied to a specific browser or device; cookie-based, probabilistic,or other;
  • 2 - IDFA
  • 3 - AAID
  • 4 - Windows Mobile Advertising ID
  • 5 - Other Mobile ID
idSTRINGREQUIREDthe actual value of the user id, provided by the user identification provider

Object: Sda

The Sda object is used in the context of Seller Defined Audiences.
KeyTypeNecessityDescription
idSTRINGOPTIONALAn exchange-specific ID for the data provider.
nameSTRINGOPTIONALAn exchange-specific name for the data provider.
segmentOBJECT ARRAYOPTIONALAn array of Segment objects that contain the actual data values.

Object: Sdc

The Sdc object is used in the context of Seller Defined Context.
KeyTypeNecessityDescription
idSTRINGOPTIONALAn exchange-specific ID for the data provider.
nameSTRINGOPTIONALAn exchange-specific name for the data provider.
segmentOBJECT ARRAYOPTIONALAn array of Segment objects that contain the actual data values.

 

Object: Segment

The Segment object is used in the context of Seller Defined Audiences/Context.
KeyTypeNecessityDescription
idSTRINGOPTIONALThe ID of the data segment specific to the data provider.
nameSTRINGOPTIONALThe name of the data segment specific to the data provider.
valueSTRINGOPTIONALThe string representation of the data segment value.

Object: Dsa

KeyTypeNecessityDescription
dsarequiredINTEGEROPTIONALa flag to indicate if DSA information should be made available. This will signal if the bid request belongs to an Online Platform/VLOP, such that a buyer should respond with DSA Transparency information based on the pubrender value.
  • 0 - Not required
  • 1 - Supported, bid responses with or without DSA object will be accepted
  • 2 - Required, bid responses without DSA object will not be accepted
  • 3 - Required, bid responses without DSA object will not be accepted, Publisher is an Online Platform
pubrenderINTEGEROPTIONALa flag to indicate if the publisher will render the DSA Transparency info. This will signal if the publisher is able to and intends to render an icon or other appropriate user-facing symbol and display the DSA transparency info to the end user.
  • 0 - Publisher can't render
  • 1 - Publisher could render depending on adrender
  • 2 - Publisher will render
datatopubINTEGEROPTIONALthe indication of whether transparency data are to be sent. Independent of the pubrender parameter, the publisher may need the transparency data for audit purposes.
  • 0 - do not send transparency data
  • 1 - optional to send transparency data
  • 2 - send transparency data
transparencyOBJECT ARRAYOPTIONALan array of objects of the entities that applied user parameters and the parameters they applied.

Object: Transparency

KeyTypeNecessityDescription
domainSTRINGOPTIONALthe domain of the entity that applied user parameters.
dsaparamsINTEGER ARRAYOPTIONALan array for platform or sell-side use of any user parameters (using the list provided by DSA Transparency Taskforce). Note: see definition and list of possible user parameters as listed here, applied consistently in both bid request and/or bid response.

Powered by