Overview

Equativ provides an OpenRTB API for suppliers which is able to receive OpenRTB bid requests and send them to its demand partners to retrieve bids on the ad 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.

Delivery rules

Equativ’s delivery rules can be used in openRTB integrations in two ways:

• Domain targeting: the delivery rule is executed for specific domains. For more information, see “Domains and bundle IDs” in Set delivery rules 
• Placement targeting: the delivery rule is executed for specific placements. A placement is a combination of a siteId, pageId, and formatId. This mode is available upon request only and requires placement data (siteId, pageId, and formatId) sent in the imp.ext.bidder extensions. For more information, see "Imp.ext.bidder object" in Open RTB API integration: bid request specification (1) and "Inventory mapping sample" in OpenRTB API integration: samples.

Miscellaneous features and limitations

• Bid requests that have either width or height set to 0 are ignored, regardless of size and format.
• The number if imp objects is limited to a maximum of 10.
• Equativ is able to return a maximum of 10 bid objects.
• Deduplication in bid responses is done by media file only (no deduplication by brand or advertiser category).

Unified bid requests

As a general rule, it is strongly recommended that callers supplying inventory to Equativ SSP send a single, unified bid request per placement. A placement corresponds to one ad opportunity. Unified bid requests add flexibility for DSPs, reduce the number of bid requests sent to Equativ, improve bid rates, and increase overall RPMA.  

Unified bid requests are either Multi-impression-object (MIO) bid requests or Multi-impression-type (MIT) bid requests.

Once the Equativ SSP receives an inbound, unified bid request (MIO/MIT bid request), it adapts its outbound bid requests to the capabilities of each DSP:

• A unified, outbound bid request is sent if the DSP supports unified bid requests.
• The inbound bid request is split into separate bid requests (for example, one bid request for banner and another bid request for native), if the DSP doesn't support unified bid requests. 

Multi-impression-object (MIO) bid requests

A Multi-impression-object (MIO) bid request is a bid request that contains multiple imp objects, for example, a banner imp object and a native imp object. MIO bid requests are used when a placement (ad opportunity) is capable of rendering multiple formats, such as banner, native or out-stream video ads. 

To ensure Equativ processes the MIO bid request as a bid request for a single placement (single ad opportunity), the tagid attribute of all imp objects must be identical. In case of different tagid attributes. or if the tagid attribute is missing, Equativ's SSP will only process the first imp object. This behavior doesn't apply to in-stream video ads: Bid requests with multiple imp objects for in-stream video ads are always processed as coming from separate placements. In the in-stream video context, the placement corresponds to a position within an ad break.

MIO bid request example: banner and native ad

The following snippet shows a MIO bid request with two impression objects: banner and native, each with a specific bidfloor. The identical tagid attribute placement-001 indicates that this bid request is for a single placement (single ad opportunity), to be monetized with either a banner or native ad.

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

MIO bid request example: two banner ads

The following snippet shows a MIO bid request with two imp objects, each for a banner with a specific bidfloor. For example, different bid floors are assigned based on the banner size or based on the deal the banner is associated with (deal objects within the pmp object).

The identical tagid attribute placement-001 indicates that this bid request is for a single placement (single ad opportunity), to be monetized with one of two banner ads.

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

MIO bid request example: two banner ads without tagid

The following snippet shows a MIO bid request with two banner objects, each with a specific bidfloor. 

The tagid attribute is omitted. Therefore, this bid request will be processed as a bid request for separate placements (separate ad opportunities), to be monetized with banner ads. Equativ's SSP will only process the first imp object in this case.

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

Multi-impression-type (MIT) bid requests 

A multi-impression-type (MIT) bid request is a bid request that contains one imp object containing a mix of banner, video, audio, or native objects. MIT bid requests are used when a placement (ad opportunity) is capable of rendering multiple formats.

MIT bid request example: banner and native ad 

The following snippet shows a bid request with one imp object containing a banner object and a native object, both sharing the same bidfloor.

"imp": [
   {
       "id": "1234",
       "banner": {
           ...
       },
       "native": {
           ...
       },
       "bidfloor": 0.4,
       "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