POST Ad API integration: parameter reference
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 POST Ad API integration: 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 | Necessity | Description |
---|---|---|---|
Placement related parameters | |||
content_source_id |
INTEGER | OPTIONAL | a 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. |
pageId |
INTEGER | REQUIRED | the 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 Create placements. |
pageName |
STRING | OPTIONAL | the 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 |
pageUrl |
STRING | OPTIONAL | the page URL; if used, it overrides the actual URL from which the ad request originates |
siteId |
INTEGER | OPTIONAL | the site ID; represents a website, mobile application or a video player; read more about sites in Create placements. |
Other parameters | |||
addtl_consent |
STRING | OPTIONAL | the additional consent string (Google); more details in chapter “Google’s additional consent mode” in Comply with Global Privacy Platform (GPP) |
ads[] |
OBJECT ARRAY | REQUIRED | the array of ad objects (see "Object: Ad" below) |
app |
OBJECT | OPTIONAL | the app object will be available soon; in the meantime, see "In-app parameters" in GET Ad API integration |
appName |
STRING | REQUIRED (for mobile in-app calls) | the application name |
bundleId |
STRING | OPTIONAL | the application bundle ID; has the form of a right-to-left domain name, e. g. com.my-app-name
|
doNotTrackId |
STRING | OPTIONAL | a user id that can be used if cookies cannot be dropped in user’s browser (e. g. for frequency capping). |
dsa |
OBJECT | OPTIONAL | see chapter "Object: Dsa" below |
eids[].source |
STRING | OPTIONAL | the user identification provider that provides the uids (see eids[].uids[] below); more details in Extended ID integration (alternative/universal IDs)
|
eids[].uids[] |
OBJECT ARRAY | OPTIONAL | the 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 ID integration (alternative/universal IDs)
|
gdpr |
BOOLEAN | OPTIONAL | indicates 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 Comply with Global Privacy Platform (GPP) |
gdpr_consent |
STRING | REQUIRED (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 Comply with Global Privacy Platform (GPP)
|
geolocation.latitude |
DOUBLE | OPTIONAL | the latitude of the device |
geolocation.longitude |
DOUBLE | OPTIONAL | the longitude of the device |
getAdContent |
BOOLEAN | OPTIONAL | if true, insertions are resolved and ads are displayed at the first call, without using nshow URLs; used only for Onecall |
gpp |
STRING | OPTIONAL | the Global Privacy Platform (GPP) consent string |
gpp_sid |
INTEGER ARRAY | OPTIONAL | an 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 |
iabframeworks |
STRING | OPTIONAL |
the supported IAB API frameworks for the given impression:
separate multiple values by a comma (e. g. |
inventoryPartnerDomain |
STRING | OPTIONAL | the inventory partner domain to designate a domain of an inventory sharing partner for purposes of ads.txt/app-ads.txt validation (see IAB specification) |
master |
STRING | OPTIONAL |
|
mraidVersion |
STRING | OPTIONAL | the 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 |
networkId |
INTEGER | REQUIRED | the network ID; identifies the network (Equativ customer’s workspace); see chapter “Authentication” in POST Ad API integration: usage for more details |
noAdCallback |
STRING | OPTIONAL | the callback used when ad response is empty (“noad”); used only when output is set to javascript |
noCookie |
BOOLEAN | OPTIONAL | if 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 Create direct insertion: general settings and delivery |
omidpn |
STRING | REQUIRED (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 |
omidpv |
STRING | OPTIONAL | “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 |
output |
STRING | OPTIONAL |
used in Generic POST requests only; requests a specific type of response; values can be either literal (e. g.
Calling specific VAST ad versions:
|
overriddenCurrency |
STRING | OPTIONAL | the ISO currency code (EUR , USD etc.); if used, overrides the network currency for CPM related macros in creative templates |
partnerExtUids |
DICTIONARY <STRING,STRING> | OPTIONAL | the dictionary partner id; user id that can be used in addition to csync cookie |
pid |
STRING | OPTIONAL | Equativ’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 |
schain |
STRING | OPTIONAL | the 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.height |
INTEGER | OPTIONAL | the height of the screen |
screen.width |
INTEGER | OPTIONAL | the width of the screen |
sda |
OBJECT ARRAY | OPTIONAL | an object containing additional user data; used for seller defined audience data; corresponds to the user.data object in open RTB integrations |
sdc |
OBJECT ARRAY | OPTIONAL | an object containing additional content data; used for seller defined context data; corresponds to the site.content.data object in open RTB integrations |
sib |
BOOLEAN | OPTIONAL | indicates if the request is used in the context of in-app header bidding or not |
srl |
STRING | OPTIONAL | the 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!) |
timestamp |
LONG | OPTIONAL | a random number mainly used for cache busting purposes |
uid |
STRING | OPTIONAL | a unique identifier for the user that can be used instead of Equativ’s pid |
us_privacy |
STRING | OPTIONAL | the CCPA (California Consumer Privacy Act) consent string; more details in: Comply with Global Privacy Platform (GPP) |
video |
OBJECT | OPTIONAL | see 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 |
---|---|---|---|
bidfloor |
FLOAT | OPTIONAL | the minimum bid price for this ad in the network currency; e.g: 0.23
|
formatId |
INTEGER | REQUIRED | the format ID; represents an ad slot on a page or in an app (e. g. medium rectangle); read more about formats in Create placements. |
headerBidding |
OBJECT | OPTIONAL | see "Object: Header bidding" below |
isLazy |
BOOLEAN | OPTIONAL | indicates 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; |
tagId |
STRING | OPTIONAL | the 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. |
target |
STRING | OPTIONAL | the 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 Set 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 ).
- 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 | Necessity | Description |
---|---|---|---|
ab |
INTEGER | REQUIRED |
the ad break; possible values:
default value: |
abpos |
INTEGER | OPTIONAL | logs 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 |
arid |
INTEGER | OPTIONAL |
the ad rule id (VideoAdRuleId); logs the application of server side ad rules when Equativ returned the video ad; possible values:
|
ctc |
STRING | OPTIONAL | the 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] |
ctch |
STRING | OPTIONAL | the name of the content channel; Key name in Video plugin*: sas_videoContentChannelName |
ctd |
STRING | OPTIONAL | the video content duration in seconds; the value -1 indicates a live stream; Key name in Video plugin*: sas_videoContentDuration; Macro name: [sas_videoContentDuration] |
ctdid |
STRING | OPTIONAL | the video content distributor Id; Key name in Video plugin*: sas_videoContentDistributorId; Macro name: [sas_videoContentDistributorId] |
ctdn |
STRING | OPTIONAL | the video content distributor name; Key name in Video plugin*: sas_videoContentDistributorName; Macro name: [sas_videoContentDistributorName] |
cte |
STRING | OPTIONAL | the 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] |
ctgr |
STRING | OPTIONAL | the genre describing the content (e. g. "Rock", "Pop") |
ctid |
STRING | OPTIONAL | the video content Id to uniquely identify the content; used for syndication purposes; Key name in Video plugin*: sas_contentid; Macro name: [sas_contentid] |
ctk |
STRING | OPTIONAL | one or multiple keywords (tags) that describe the video content (separated by comma); Key name in Video plugin*: sas_videoContentTags; Macro name: [sas_videoContentTags] |
ctlg |
STRING | OPTIONAL | the language of the content; format ISO-639-1-Alpha-2 is strongly recommended |
ctmsid |
STRING | OPTIONAL | the content management system Id in charge of the video content; Key name in Video plugin*: sas_videoCmsId; Macro name: [sas_videoCmsId] |
ctn |
STRING | OPTIONAL | the video content name (title); Key name in Video plugin*: sas_contentTitle; Macro name: [sas_contentTitle] |
ctnw |
STRING | OPTIONAL | the name of the content network; Key name in Video plugin*: sas_videoContentNetworkName |
ctp |
STRING | OPTIONAL | the video content provider name; Key name in Video plugin*: sas_contentProviderName; Macro name: [sas_contentProviderName] |
ctpid |
STRING | OPTIONAL | the video content provider ID; used for syndication purposes; Key name in Video plugin*: sas_contentproviderid; Macro name: [sas_contentproviderid] |
ctr |
STRING | OPTIONAL | the 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] |
cts |
STRING | OPTIONAL | the video content season number; Key name in Video plugin*: sas_videoSeasonNumber; Macro name: [sas_videoSeasonNumber] |
ctt |
STRING | OPTIONAL | the 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] |
ctxid |
STRING | OPTIONAL | the video content id in an external (3rd party) system; Key name in Video plugin*: sas_externalContentId; Macro name: [sas_externalContentId] |
ec |
INTEGER | OPTIONAL | logs the video error code, if an error occurred; for more information, see Video error code reference. |
live |
BOOLEAN | OPTIONAL | default 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 |
mabd |
STRING | OPTIONAL | the maximum adbreak duration; sets a duration limit for the ad pod (in seconds) |
pb |
INTEGER | OPTIONAL | the 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; for more information, see Set video ad pod position targeting
|
ps |
INTEGER | OPTIONAL | the ad pod size; specifies the number of sequenced ads to be returned in the VAST ad response, default value: 1
|
skip |
BOOLEAN | OPTIONAL | declares a video as being skippable or not in the bid request |
ssar |
BOOLEAN | OPTIONAL |
determines which video ad rules should be applied;
|
vbrmax |
INTEGER | OPTIONAL | the maximum bitrate of the video creative served programmatically, in Kbps; must have a positive value |
vbrmin |
INTEGER | OPTIONAL | the minimum bitrate of the video creative served programmatically, in Kbps; must have a positive value |
vcn |
STRING | OPTIONAL |
a 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. |
vct |
INTEGER | OPTIONAL |
the video client technology Id passed by Equativ's video plugin; possible values:
|
vd |
STRING | OPTIONAL | logs the video ad duration in seconds |
vdmax |
INTEGER | OPTIONAL | the maximum duration of the video creative served programmatically, in seconds; must have a positive value; default value: 60
|
vdmin |
INTEGER | OPTIONAL | the minimum duration of the video creative served programmatically, in seconds; must have a positive value, greater than or equal to 1; default value: 1
|
vit |
INTEGER | OPTIONAL |
the video integration type passed by Equativ’s video plugin; possible values:
|
vpaidt |
STRING | OPTIONAL | the VPAID type; vpaidt=js requests the VPAID type javascript |
vpaidv |
INTEGER | OPTIONAL |
the VPAID version;
|
vph |
INTEGER | OPTIONAL | the video player height, in pixels |
vplcmt |
INTEGER | OPTIONAL |
the video placement type in accordance with updated IAB Digital Video Guidelines; replaces
|
vpmt |
INTEGER | OPTIONAL |
the video playback method; set to -1 by default (feature disabled):
|
vpt |
INTEGER | OPTIONAL |
the 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
|
vpva |
STRING | OPTIONAL | logs the area of the video ad that was viewed, in percent (VideoPercentageViewedArea ) |
vpw |
INTEGER | OPTIONAL | the video player width, in pixels |
vrn |
STRING | OPTIONAL | the 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 integration (see chapter: "In-app parameters").
Object: Header bidding
The header bidding object is used in the context of Unified auction integrations (see Set up and manage unified auction): 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 |
---|---|---|---|
bidder |
STRING | REQUIRED | the name of the bidder that won the header auction |
cpm |
DECIMAL | REQUIRED | the 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
|
currency |
STRING | OPTIONAL | the currency of the header auction winner’s bid price, expressed as an ISO 4217 3-letter currency code; e.g.: EUR
|
dealId |
STRING | OPTIONAL | the 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 ID integration (alternative/universal IDs).
Key | Type | Necessity | Description |
---|---|---|---|
atype |
INTEGER | OPTIONAL |
the agent type the ID is coming from:
|
id |
STRING | REQUIRED | the 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 and contexts.
Key | Type | Necessity | Description |
---|---|---|---|
id |
STRING | OPTIONAL | An exchange-specific ID for the data provider. |
name |
STRING | OPTIONAL | An exchange-specific name for the data provider. |
segment |
OBJECT ARRAY | OPTIONAL | An array of Segment objects that contain the actual data values. |
Object: Sdc
The Sdc
object is used in the context of seller defined audiences and contexts.
Key | Type | Necessity | Description |
---|---|---|---|
id |
STRING | OPTIONAL | An exchange-specific ID for the data provider. |
name |
STRING | OPTIONAL | An exchange-specific name for the data provider. |
segment |
OBJECT ARRAY | OPTIONAL | An array of Segment objects that contain the actual data values. |
Object: Segment
The Segment
object is used in the context of seller defined audiences and contexts.
Key | Type | Necessity | Description |
---|---|---|---|
id |
STRING | OPTIONAL | The ID of the data segment specific to the data provider. |
name |
STRING | OPTIONAL | The name of the data segment specific to the data provider. |
value |
STRING | OPTIONAL | The string representation of the data segment value. |
Object: Dsa
Key | Type | Necessity | Description |
---|---|---|---|
datatopub |
INTEGER | OPTIONAL |
the indication of whether transparency data are to be sent. Independent of the
|
dsarequired |
INTEGER | OPTIONAL |
a 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 |
INTEGER | OPTIONAL |
a 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.
|
transparency |
OBJECT ARRAY | OPTIONAL | an array of objects of the entities that applied user parameters and the parameters they applied. |
Object: Transparency
Key | Type | Necessity | Description |
---|---|---|---|
domain |
STRING | OPTIONAL | the domain of the entity that applied user parameters. |
dsaparams |
INTEGER ARRAY | OPTIONAL | an 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. |