This specification is intended for Supply-Side platforms who want to integrate with E- Planning to sell their inventory. Complying with this specification will allow for a faster and more efficient integration to E-Planning’s production environment.

Auction

What is often referred to as an “auction” consists of:

A bid request being sent to E-Planning (among other buyers)
E-Planning returning a bid response
The partner selecting a winner (if any)
The partner allowing the winner to display an ad to the user

Each of these steps will be specified in this document, along with parallel but equally important operations such as user matching.

RTB Server-to-Server Protocol

E-Planning uses JSON and the HTTP POST method.
E-Planning returns HTTP 204 to signal that it does not want to enter the auction.
The E-Planning RTB protocol and spec was built upon OpenRTB 2.3. However, some OpenRTB 2.5 features are supported (like Banner.format).

Bid Request

To invite E-Planning to enter an auction, the partner will be provided with a set of URLs (“endpoints”), each of them pointing to a different E-Planning data center. The general intent is that the data center closest to the partner’s data center should be used. Please reach out to your E-Planning technical contact for more details.

Only one bid request should be sent for a given auction, but multiple impression slots of the same can and should be included within a single bid request. The JSON file should have the structure below.

Mandatory fields must be included.
Recommended fields have positive impact on bidding pattern when implemented properly.
Optional fields have positive impact on operations and reporting.

Request Top-Level Object

Field	Type	Status	Comment
id	String	Mandatory	An identifier for the request, it can be used to connect the bid request to the bid response outside of the HTTP protocol
tmax	Integer	Recommended	In milliseconds, the time after which bid responses will not enter the auction
at	Integer	Mandatory	Auction type, where 1 = First Price, 2 = Second Price Plus
imp	Object Array	Mandatory	See Imp object
allimps	Integer	Recommended	Flag to indicate whether all the impressions of the context are available or not
user	Object	Mandatory	See User object
device	Object	Mandatory	See Device object
site	Object	Mandatory for Web	See Site object
app	Object	Mandatory for In-App	See App object
source	Object	Mandatory	See Source object
regs	Object	Mandatory	See Regs object
badv	String Array	Recommended	Block list of advertisers by their domains
bcat	String Array	Recommended	Blocked advertiser categories using the IAB content categories

Example

{
	"id": "bfebe4d6f24efacd",
	"tmax": 300,
	"at": 1,
	"cur": ["USD"],
	"imp": [{ "...": "..." }],
	"user": { "...": "..." },
	"device": { "...": "..." },
	"site": { "...": "..." },
	"source": { "...": "..." },
	"regs": { "...": "..." },
	"badv": ["ford.com","bmw.com"],
	"bcat":, ["IAB8-1","IAB8-2"]
}

Imp Object

Field	Type	Status	Comment
id	String	Mandatory	A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments)
banner	Object	Mandatory	A Banner object
bidfloorcur	String	Mandatory	Currency in which the bid response is expected, including the floor prices. using ISO-4217 alpha codes. Example: "USD"
bidfloor	Float	Mandatory	The minimum amount for which the impression can be sold, expressed in the currency set in bidfloorcur
secure	Integer	Mandatory	Set to1 if the snipped in the bid response must use HTTPS
instl	Integer	Recommended	Set to 1 when the impression is destined to be an interstitial or full- page
clickbrowser	Integer	Mandatory for In-App	Indicates the type of browser which should be opened upon clicking the creative in an app, where 0 = embedded, 1 = native

Example

{
	"id": "1",
	"bidfloor": 0.4286,
	"bidfloorcur": "USD",
	"secure": 1,
	"instl": 0,
	"banner": {
		"w": 300,
		"h": 250,
		"pos": 1,
		"topframe": 0
	},
	"tagid": "79a4e192e54cc0d9"
}

Banner Object

Field	Type	Status	Comment
format	Object Array	Mandatory if “w” and “h” are not set	See Format Object. Formats allowed in the auction; it is an array to reflect the fact that many publisher placements support several sizes considered as part of one auction (e.g. 300x250 or 300x600).
w	Integer	Mandatory if “format” is not set	Width in pixels of the banner supported size
h	Integer	Mandatory if “format” is not set	Height in pixels of the banner supported size
wmin	Integer	Recommended if “format” is not set	Minimum width in pixels of the banner supported size
wmax	Integer	Recommended if “format” is not set	Maximum width in pixels of the banner supported size
hmin	Integer	Recommended if “format” is not set	Minimum height in pixels of the banner supported size
hmax	Integer	Recommended if “format” is not set	Maximum height in pixels of the banner supported size
pos	Integer	Recommended	Follows the Ad Position IAB standard for Above-The-Fold, Below-The-Fold, etc.
topframe	Integer	Recommended	Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes
api	Integer	Recommended	List of supported API frameworks for this impression as described in OpenRTB 2.5. If you are sending inApp traffic, please consider add OMID-1 flag (7) if is supported.
battr	Integer Array	Recommended	Blocked creatives attributes
btype	Integer Array	Recommended	Blocked banner ad types
expdir	Integer Array	Optional	Directions in which the banner may expand

Both OpenRTB 2.3 and 2.5 size formats are supported. We strongly recommend to not set both at the same time, but if you do, OpenRTB 2.5 format will be discarded.
- OpenRTB 2.3: Is "w" and "h"
- OpenRTB 2.5: Is "format"
If the intent is to sell two placements on a single page, for example a 728x90 “leaderboard” at the top of the page and a 300x250 rectangle on the right-hand side of the page, two impressions objects should be present with a single size object in each
If the intent is to sell a single placement that can host either a 300x250 rectangle creative or a 300x600 “half-page” creative, then only one impression object should be present, with two size objects in the array

Example

Using format

{
	"pos": 1,
	"format": [
		{
			"w": 300,
			"h": 600
		},
		{
			"w": 300,
			"h": 250
		}
	],
	"battr": [ 11, 12 ],
	"btype": [ 4 ]
}

Using w and h

{
	"pos": 1,
	"w": 300,
	"h": 250,
	"wmin": 300,
	"wmax": 300,
	"hmin": 50,
	"hmax": 600,
	"battr": [ 11, 12 ],
	"btype": [ 4 ]
}

Format Object

Field	Type	Status	Comment
w	Integer	Mandatory	Width in pixels of a supported size
h	Integer	Mandatory	Height in pixels of the same supported size

Site Object

Field	Type	Status	Comment
id	String	Mandatory	Exchange-specific site ID
page	String	Mandatory	The URL of the page on which the impression will be shown; field should be absent when unknown or alternatively an empty string
publisher	Object	Mandatory	See Publisher Object
domain	String	Recommended	The domain of the page
cat	String Array	Recommended	Array of IAB content categories of the site as described in OpenRTB 2.5. Max 8 categories.
ref	String	Recommended	The referrer URL that caused navigation to the current page

Example

{
	"id": "123",
	"page": "http://example.com/section/page.html",
	"cat": [ "IAB1-2" ],
	"publisher": {
		"id": "456",
		"domain": "example.com",
		"name": "Example Inc"
	}
}

App Object

Field	Type	Status	Comment
id	String	Obligatorio	Exchange-specific app ID
name	String	Obligatorio	The application’s name
bundle	String	Obligatorio	Application bundle or package name (e.g. "com.foo.mygame" on Android and numeric on iOS)
domain	String	Recomendado	Application domain
storeurl	String	Recomendado	Application store URL (e.g. iTunes store URL or Android store URL)
cat	String Array	Recomendado	Array of IAB content categories of the site as described in OpenRTB 2.5. Max 8 categories.

Example

{
	"id": "12345",
	"name": "My App",
	"bundle": "com.foo.myapp",
	"domain": "myapp.com",
	"storeurl": "https://store.com/app/12345",
	"cat": [ "IAB1-2" ],
	"publisher": {
		"id": "456",
		"domain": "example.com",
		"name": "Example Inc"
	}
}

Publisher Object

Field	Type	Status	Comment
id	String	Mandatory	The publisher’s unique ID; it should be sufficient to identify the party ultimately being paid for the impression auctioned. Cannot be null
domain	String	Recommended	Highest-level domain of the publisher
name	String	Recommended	Name of the publisher

Example

{
	"id": "456",
	"domain": "example.com",
	"name": "Example Inc"
}

User Object

Field	Type	Status	Comment
id	String	Recommended	The user’s ID (SSP wide)
buyeruid	String	Recommended	The E-Planning’s user ID. See user matching section below for comments on how it is obtained

Example

{
	"id": "1234567",
	"buyeruid": "e3cf38b549b50e01",
	"consent": "BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA"
}

Device Object

Field	Type	Status	Comment
ua	String	Mandatory	The browser user agent string
ip	String	Mandatory	The user's IP address
dnt	Integer	Recommended	The user’s intent regarding tracking. If a dnt value was sent in the header by the client application when calling the partner, the value 1 should be passed in this field; if no value was sent, it should be 0.
language	String	Optional	The user’s browser language using ISO- 639-1-alpha-2
carrier	String	Recommended	Carrier or Internet Service Provider
connectiontype	Integer	Recommended	Network connection type
os	String	Recommended	The device OS
geo	Object	Recommended	See the Geo Object
ifa	String	Recommended	Only for In-App. The device’s advertising ID

Example

{
	"ip": "142.93.199.194",
	"ua": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10.12; rv:71.0) Gecko\/20100101 Firefox\/71.0",
	"os": "macOS",
	"carrier": "verizon",
	"connectiontype": 6,
	"dnt": 0,
	"geo": {
		"country": "USA",
		"city": "Stanford"
	}
}

Geo Object

Field	Type	Status	Comment
country	String	Mandatory	The user's country at the time of the display, using ISO- 3166-1-alpha-3
city	String	Recommended	The user's city
latitude	Float	Recommended	Latitude from -90.0 to +90.0, where negative is south
longitude	Float	Recommended	Longitude from - 180.0 to +180.0, where negative is west

Example

{
	"latitude": 37.4194,
	"longitude": -122.164,
	"country": "USA",
	"city": "Stanford"
}

Regs Object

Field	Type	Status	Comment
coppa	Integer	Recommended	Flag indicating if this request is subject to COPPA regulations, where 0 = no, 1 = yes
gdpr	Integer	Mandatory for EU users (Recommended otherwise)	Flag indicating if this request is subject to the GDPR regulations, where 0 = no, 1 = yes
ext.consent	String	Recommended	When the request is subject to GDPR regulations, this field is used to indicate the user's consent string
us_privacy	String	Recommended	Flag indicating is this request is subject to the CCPA (California Consumer Privacy Act) regulations. CCPA field should be exactly 4 chars length, with first char must be 1 (correspond to version), the 3 remaining chars must be either 'Y' or 'y', 'N or 'n', '-'. https://iabtechlab.com/wp-content/uploads/2019/11/U.S.-Privacy-String-v1.0-IAB-Tech-Lab.pdf

Example

{
	"gdpr": 1,
	"coppa": 1,
	"us_privacy": "1-N-",
	"ext": {
		"consent": "BOq9e8JOq9e8lAHABBESCv- AAAAst7_______9______9uz_Ov_v_f__33e8__9v_l_7_-___u_-3zd4u_1vf99yfm1-7etr3tp_87ues2_Xur__79__3z3_9pxP78k89r7337Ew_v-_v8b7BCIJ"
	}
}

Source Object

Field	Type	Status	Comment
fd	Integer	Mandatory	Entity responsible for the final impression sale decision, 0 = exchange / 1 = upstream source
pchain	String	Recommended if "schain" is not set	TAG payment ID chain string
ext.schain	String	Recommended if "pchain" is not set	Per IAB's supply chain object proposal
ext.omidpn	String	Recommended if inApp	Identifier of the OM SDK integration
ext.omidpv	String	Recommended if inApp	Version of the OM SDK integration

For pchain implementation we accept both TAG ID or domain identification

Example

Using pchain

{
	"fd": 1,
	"pchain": "directseller.com:12345"
}

Using schain

{
	"fd": 1,
	"ext": {
		"schain": {
			"complete": 1,
			"nodes": [
				{
					"asi":"directseller.com",
					"pid":"12345",
					"rid":"c7ecc1f7b1628d49"
				}
			]
		}
	}
}

Bid Request example

Example of a banner bid request (web)

{
	"id": "6cb84abfabb2990d",
	"tmax": 300,
	"at": 1,
	"cur": ["USD"],
	"imp": [{
		"id": "1",
		"bidfloor": 0.4,
		"secure": 1,
		"instl": 0,
		"banner": {
			"w": 300,
			"h": 600,
			"pos": 1,
			"topframe": 0
		}
	}],
	"user": {
		"id": "2e6r4g56ez1hz8er4h",
		"buyeruid": "e3cf38b549b50e01"
	},
	"device": {
		"ip": "171.67.194.75",
		"ua": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10.12; rv:71.0) Gecko\/20100101 Firefox\/71.0",
		"os": "macOS",
		"carrier": "verizon",
		"connectiontype": 1,
		"dnt": 0,
		"lmt": 0,
		"geo": {
			"country": "USA",
			"city": "Stanford"
		}
	},
	"site": {
		"id": "123",
		"page": "http://example.com/section/page.html",
		"cat": [ "IAB1-2" ],
		"publisher": {
			"id" : "456",
			"domain": "example.com",
			"name": "Example Inc"
		}
	}
	"source": {
		"fd": 1,
		"ext": {
			"sourcetype": 3,
			"sourceorigin": 7,
			"schain": {
				"complete": 1,
				"nodes": [{
					"asi":"directseller.com",
					"pid":"456",
					"rid":" c7ecc1f7b1628d49"
				}]
			}
		}
	},
	"regs": {
		"gdpr": 1,
		"us_privacy": "1-N-",
		"coppa": 1,
		"ext": {
			"consent": "BOq9e8JOq9e8lAHABBESCv- AAAAst7_______9______9uz_Ov_v_f__33e8__9v_l_7_-___u_-3zd4u_1vf99yfm1- 7etr3tp_87ues2_Xur__79__3z3_9pxP78k89r7337Ew_v-_v8b7BCIJ"
		}
	},
	"badv": ["ford.com","bmw.com"],
	"bcat": ["IAB8-7","IAB8-8"]
}

Bid Response

Each bid response generated by E-Planning is unique and must be used only once, on the same context of the original bid request.

Response Top-Level Object

Field	Type	Comment
id	String	E-Planning returns here the identifier present in the corresponding bid request; this is not necessary for the protocol but allows to match the request and response outside of the HTTP bidding protocol.
seatbid	Object Array	See seatbid object. This is an array to accommodate OpenRTB and partner deserialization, but E-Planning will always return a single object inside it.
cur	String	The currency of the bid using ISO-4217 alphabetic codes.

Seatbid Object

Field	Type	Comment
seat	String	An identifier, commonly used to reflect E-Planning’s billing requirement in the bidding process.
bid	Object Array	See Bid object

Bid Object

Bid being an array of objects, it explicitly allows for several bids to be present in the bid response.

Field	Type	Comment
id	String	Bidder generated bid ID to assist with logging/tracking.
impid	String	E-Planning returns here the imp identifier passed in the bid request.
price	Float	E-Planning’s bid in CPM value (1 means that E- Planning is willing to pay 0.001 for this single impression).
adm	String	The creative ad markup to pass to the browser if the bid wins the auction; the markup includes a macro that must be replaced by the partner with the price it will be charged, in CPM value.
adomain	String Array	The domain of the advertiser E-Planning is placing a bid for.
w	Integer	The width of the ad (to remove ambiguity when the placement allowed for multiple sizes to compete).
h	Integer	The height of the ad (to remove ambiguity when the placement allowed for multiple sizes to compete).

E-Planning counts the impression via creative code on adm, in consequence nurl is not supported.

Bid Response example

Example of a banner bid response (web)

{
	"id": "658cc151efd92b1b",
	"cur": "USD",
	"seatbid": [
		{
			"seat": "9ac35426a22738bc",
			"bid": [
				{
					"id": "9c53f0f503c6a52d",
					"impid": "1",
					"price": 1.07,
					"w": 300,
					"h": 250,
					"adm": "<script type='text/javascript' src='https://ads.us.e-planning.net/sample/ad '></script><img src='https://u-iad02-i01.e-planning.net/eli/1/5a1ad71d2d53a0f5?b=018b8f1a3b2a9341&s=9ac35426a22738bc&p =${AUCTION_PRICE:B64}' />",
					"adomain": ["advertiser.com"]
				}
			]
		}
	]
}

Auction pricing macros

When a E-Planning bid wins an auction, you can inform E-Planning what the winning price was using the auction price macro.
Auction price macro is inserted in Bidresponse.seatbid[...].bid[...].adm and should be replaced inline. Please use the same currency than the auction (usually USD).

There are two different pricing macros:

${AUCTION_PRICE} – Should be replaced with the winning price CPM
${AUCTION_PRICE:B64} – Same than ${AUCTION_PRICE} but base64 encoded

E-Planning will use the base64-encoded macro by default. Please notify your technical contact if you do not support it.

User Matching

E-Planning provides partner with a sync URL, which partner should fire from traffic using an IFRAME tag. After URL is called from user's browser E-Planning will handle user's cookies on its side. Then E-Planning will redirect the user to a redirect URL which SSP provides to E- Planning.

There is a placeholder in this redirect URL, which E-Planning will replace with buyeruid generated on our side. This process only applies to Web auctions, not being necessary in In-App.

Example of supply partner’s redirect URL: http://test-partner-domain.com/?uid=$UID, E-Planning will replace $UID placeholder with some buyeruid (e.g. “e3cf38b549b50e01”) and redirect user using this URL.
Partner shall pass a redirect URL as "redir" parameter in E-Planning sync URL:

https://ads.us.e-planning.net/uspd/1/<CLIENT_ID>?ruidm=1&du=<ENCODED_REDIRECT_URL>

Note <CLIENT_ID> is provided by E-Planning

Here is the example of final sync IFRAME tag:

<iframe src="https://ads.us.e-planning.net/uspd/1/5a1ad71d2d53a0f5?ruidm=1&du=https%3A%2F%2Ftest-partner-domain.com%2F%3Fuid%3D%24UID" width="0" height="0" style="display: none;"></iframe>

It will redirect to:

https://test-partner-domain.com/?uid=e3cf38b549b50e01

buyeruid format

E-Planning’s buyeruid is a fixed 16 characters length string in all cases, eg: "e3cf38b549b50e01"

Compression

E-Planning can receive compressed bid requests from partners and send them back compressed bid responses. E-Planning recommends usage of compression in requests and responses to decrease auction latency and save network bandwith.

In order for our engine to properly handle a gzipped request, the HTTP header Content-Encoding: gzip must be present in the bid request.
In order for our engine to properly generate a gzipped response, the HTTP header Accept-Encoding: gzip must be present in the bid request.

For information, by default, all partners receive non-compressed bid responses from E-Planning.

Persistent connections

E-Planning supports HTTP Keep-Alive connections. By sending the Connection: Keep-Alive header, multiple bid requests can be sent over the same TCP connection. This reduces auction latency by avoiding the TCP handshake for every bid request sent. E-Planning recommends the usage of persistent connections.

Contents

Auction

RTB Server-to-Server Protocol

Bid Request

Request Top-Level Object

Example

Imp Object

Example

Banner Object

Example

Using format

Using w and h

Format Object

Site Object

Example

App Object

Example

Publisher Object

Example

User Object

Example

Device Object

Example

Geo Object

Example

Regs Object

Example

Source Object

Example

Using pchain

Using schain

Bid Request example

Example of a banner bid request (web)

Bid Response

Response Top-Level Object

Seatbid Object

Bid Object

Bid Response example

Example of a banner bid response (web)

Auction pricing macros

User Matching

buyeruid format

Compression

Persistent connections