Overview

Equativ provides an OpenRTB API for suppliers which is able to receive OpenRTB bid requests. Equativ then runs an auction for each request so Equativ’s demand partners can bid on the opportunity. This guide explains to suppliers how to use the API, including setup, configuration as well as the supported objects and parameters.

Equativ’s OpenRTB API for suppliers supports the OpenRTB 2.6 framework.

Supported impression/inventory/environment types

Equativ supports:

• banner, in-stream video, out-stream video, audio (both via video and audio objects) and native impression types
• AMP and rewarded video inventory types
• desktop web, mobile web and in-app environment types

API features and limitations 

Equativ’s OpenRTB API has the following features and limitations:

• insertions, set up in Monetization, are not supported – the ad markup returned from the DSP is sent directly to the publisher
• creative templates are not supported; the only modifications Equativ performs on the ad markup retrieved from DSPs are to:
  • wrap the ad markup into a simple <script> to add Equativ’s impression counting pixel
  • wrap any VAST responses in a VAST wrapper to include Equativ’s counting pixels
• ⚠️ Any call to Equativ’s OpenRTB API is handled as an open auction. Equativ does not take into account any deals (deal Ids) received in the bid request! However, deals can be set up in Monetization and sent to downstream DSPs, i. e. to Equativ’s demand partners
• bid requests that have either width or height set to 0 will be ignored, regardless of size and format.
• Equativ’s delivery rules can be targeted to domains and are available by domain. Additionally, upon request, the delivery rules can be targeted to Equativ placements (sites/pages/formats) and reports are available at placement granularity, if the placement data (siteId/pageId/formatId) is sent in the imp[].ext.bidder.<itemId> extensions (see "Imp[].ext.bidder object" in Open RTB API integration: bid request specification (1) and "Inventory mapping sample" in OpenRTB API integration: samples).
• for rewarded video monetization, it is strongly recommended to follow the OpenRTB 2.6 specification, which explicitly standardizes the signaling of rewarded formats using the imp.rwdd field; the standard is not limited to the video context only – any impression types can be declared and monetized as rewarded. Failure to properly declare rewarded inventory may lead to classification as invalid traffic (IVT).

Read the Server-side header bidding: overview article for further details.

Multi-impression-type bid requests 

The Equativ SSP is able to ingest and send bid requests with an imp object containing multiple impression types. For instance, the imp object shown in the sample below contains both a banner and a native object, signaling that the given ad opportunity can be monetized with either a banner ad or with a native ad: 

imp: [
  {
   "id": "1234",
   "banner": {...},
   "native": {...},
   "bidfloor": 0.4,
   "bidfloorcur": "USD",
  }
]

Multi-imp-object bid requests

The Equativ SSP is also able to ingest and send bid requests containing multiple imp objects for the same tagid (placement), with different impression types, each having its own associated parameters (bid floor, deal etc.). For instance, the two imp objects in the sample below are for the same tagid (placement-001), but each imp object has it own impression type (banner / native) and its associated bidfloor (0.4 / 1.3):

imp: [
 {
  "id": "1234",
  "tagid": "placement-001",
  "banner": {...},
  "bidfloor": 0.4,
  "bidfloorcur": "USD",
 },
 {
  "id": "5678",
  "tagid": "placement-001",
  "native": {...},
  "bidfloor": 1.3,
  "bidfloorcur": "USD",
 }
     ]

Invoicing

Any currency Equativ is able to bill can be sent in the bid request. Equativ responds in the account’s currency, i. e. in the currency defined in the Equativ network.

All auctions (bid requests and bid responses) are transacted as first price auctions and prices are expressed as net prices, i. e. the bid prices and the win prices both correspond to the price that Equativ will pay to the supplier.

Authentication 

To authenticate, you must send the Equativ network ID in any bid request to Equativ’s OpenRTB API. The network ID represents your account at Equativ. You will receive the network ID from your contact at Equativ.

Bid requests without the Equativ network cannot be routed into your account and will be discarded! There are two methods to pass the network ID:

• replacing your own publisher ID by your Equativ network ID via the site.publisher.id or app.publisher.id field of the bid request; this method is available out of the box
• using the extension field bidRequest.ext.network_id (integer); example: bidRequest.ext.network_id = 0; this method is available upon request only - get in touch with your contact at Equativ if you intend to use it

Bidder endpoint

Once contractual agreements are signed, Equativ will provide you with the endpoint URLs. Equativ operates data centers in the regions: EU, APAC, US-West, US-East.

User-sync endpoint

GDPR parameters are required in all contexts to comply with the regulation. Non-compliant requests will be rejected. The user-sync endpoint reads the &gdpr= and &gdpr_consent= parameters to determine if an ID for the user can be matched or not. Read the IAB TCF v2 specification for URL-based services for further details.

The supplier is hosting the matching table so that the bid requests will be sent with the signal user.buyeruid which contains the Equativ user ID.

Equativ will respond with an HTML file including syncURLs with its demand partners as well as the syncURL of the network with the Equativ user ID value - see "Equativ user sync response sample" in OpenRTB API integration: samples.

It is also possible to respond with a simple 302 redirect to the network. However, this sync mechanism is less efficient. Calling the is user-sync endpoint feeds into a geo-balanced server-side store used at auction time to map from the user.buyeruid in the received bid request. The write operation on the server-side store occurs only on a single data center, selected based on the IP address of the caller to the sync endpoint and is not automatically propagated to other regions. Therefore, each region remains isolated.

To prevent bid request rejection due to failed or missing user-sync look-ups, make sure you:

• initiate user-sync calls from the client device of the user being synchronized; preserve the caller IP address to ensure their location is properly detected and the write operation will occur in the most appropriate regional store.
• send bid requests for a given user to Equativ’s bidder endpoint that is closest to the IP location of the client’s device

Headers

• make sure you request a "Content-Type: application/json"
• to compress responses, the Equativ OpenRTB API supports Accept-Encoding (gzip or br)
• to compress requests, the Equativ OpenRTB API supports Content-Encoding: gzip

HTTP status codes

Frequently Asked Questions

FAQ about imp objects containing multiple video objects 

• To get multiple bid objects, do you expect the supplier to simply send an imp object array, each containing a video object?
  • yes
• What is the maximum number of imp objects supported?
  • Max. 10 imp objects
• What is the maximum number of bid objects Equativ is able to return?
  • Max. 10 bid objects
• If the bidrequest object contains, for instance, 8 imp objects, how many responses would Equativ return?
  • From 0 to 8 imp objects, depending on how many can be filled by the demand side.

Miscellaneous FAQ

• Does Equativ support multi-impression object requests?
  • Only for the video object
• In terms of media file, brand or advertiser category, does Equativ deduplicate bids in a response for a multi-impression opportunity?
  • Deduplication is done by media file only; no deduplication by brand/advertiser category
• Are the impression trackers among all bid responses for a single bid request distinct from one another?
  • Yes