Skip to content

Bid request

POST https://api.elo.ad/v1/rtb/bid

Send an OpenRTB 2.6 bid request as JSON, with Content-Type: application/json.

Send your publisher API key in the Authorization header:

Terminal window
Authorization: Bearer $ELO_PUBLISHER_API_KEY

The key starts with elo_pub_. It is the same key for every request, and it tells Elo which partner sent the request. Keep it on your server. See Onboarding to create one and have bidding turned on.

Elo reads only the fields below and ignores the rest, so you can send a full OpenRTB 2.6 request as it is.

FieldRequiredUse
idyesEchoed in the bid response.
impyesAt least one impression. Only imp[0] is read.
imp[0].idyesEchoed as the bid’s impid.
imp[0].native.requestyesThe Native 1.2 request, as a JSON string or an object. A Native 1.0 or 1.1 request wrapped in a native object is also read. It must have at least one asset.
imp[0].tagidnoStored for reporting.
imp[0].bidfloornoThe floor CPM. Elo does not bid when the floor is above its price. Default 0.
imp[0].bidfloorcurnoMust be USD. Default USD.
imp[0].ext.elonoContext that has no standard field, such as intent. See Context.
site or appnokeywords, kwarray, cat, sectioncat and pagecat are matched on. site.domain or app.bundle is stored for reporting. When both are sent, site is read.
site.content or app.contentnotitle, keywords, kwarray and cat are matched on.
user.keywords, user.kwarraynoMatched on.
device.geo.countryyes, to get a bidThe user’s country, as ISO 3166-1 alpha-3 (USA) or alpha-2 (US).
regs.coppanoElo does not bid when it is 1.
tmaxnoThe time you wait for an answer, in milliseconds.
testno1 for a test request. See Testing.

A request needs at least one keyword, intent, category or content title, from the standard fields or from imp[0].ext.elo, or Elo does not bid.

Category codes in cat, sectioncat, pagecat and content.cat can be from the IAB Content Taxonomy 1.0 (IAB17, IAB19-6) or 3.0 (483). Elo reads a 1.0 subcategory such as IAB19-6 as its top category, IAB19.

Elo does not store the user’s IP address, user agent or user ID. It bids on context only, so it does not read regs.gdpr or consent strings.

Elo bids on the context of the conversation, so send as much of it as you have. Put it in the standard fields above, in imp[0].ext.elo, or in both. Elo matches on all of it together and counts a term sent twice once.

imp[0].ext.elo holds context that OpenRTB has no field for:

keywords Type array of strings
["trail running", "shoes"]
intent Type string
"buy running shoes"
topic Type string
"marathon training"
categories Type array of IAB category names
["Sports"]
"imp": [
{
"id": "1",
"native": { "request": "..." },
"ext": {
"elo": {
"keywords": ["trail running", "shoes"],
"intent": "buy running shoes",
"conversation_id": "c-1029"
}
}
}
]

Elo matches the request above on trail running, shoes and buy running shoes. It reads every string and string-array value in the object, so other text fields are matched on too. Fields whose name ends in id, such as conversation_id, are left out, and so are numbers and nested objects. Send derived context, such as keywords and intent, not the user’s messages.

If your platform already keeps context in an imp[0].ext object of its own, you do not need to copy it into elo. Tell Elo the object’s name at onboarding, and Elo reads it the same way. Elo reads no other ext object: not one in imp under another name, and not ext in site, app, user, device, regs or the request itself.

Elo answers these Native 1.2 assets:

AssetAnswer
titleThe ad title, cut to len.
img type 3 (main)The ad’s main image, or its icon when it has no main image.
img type 1 (icon) or 2 (logo)The ad’s icon.
data type 1 (sponsored)The ad title, cut to len.
data type 2 (description)The ad’s description, cut to len.
data type 11 (display URL)The advertiser’s domain, cut to len.
data type 12 (call to action)The button text, cut to len.

Elo does not answer video assets or other data types. When the request marks such an asset required: 1, Elo does not bid; when the asset is optional, the response leaves it out.

Terminal window
curl -X POST "https://api.elo.ad/v1/rtb/bid" \
-H "Authorization: Bearer $ELO_PUBLISHER_API_KEY" \
-H "Content-Type: application/json" \
-d @bid-request.json

bid-request.json:

{
"id": "4f1c2b7e-9a3d-4c55-8e21-6b0f3a9d7c10",
"imp": [
{
"id": "1",
"tagid": "chat-inline",
"bidfloor": 1.0,
"ext": {
"elo": {
"keywords": ["running shoes", "marathon training"],
"intent": "buy running shoes"
}
},
"bidfloorcur": "USD",
"native": {
"ver": "1.2",
"request": "{\"ver\":\"1.2\",\"context\":1,\"plcmttype\":1,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":40}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"wmin\":300,\"hmin\":157}},{\"id\":3,\"required\":0,\"img\":{\"type\":1,\"w\":64,\"h\":64}},{\"id\":4,\"required\":1,\"data\":{\"type\":2,\"len\":90}},{\"id\":5,\"required\":0,\"data\":{\"type\":1}},{\"id\":6,\"required\":0,\"data\":{\"type\":12,\"len\":15}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1]}]}"
}
}
],
"site": {
"domain": "chat.example.com",
"cat": ["IAB17"],
"content": {
"title": "Training for a first marathon",
"cat": ["483"]
}
},
"device": {
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
"ip": "203.0.113.7",
"geo": { "country": "USA" }
},
"user": { "keywords": "fitness" },
"regs": { "coppa": 0 },
"tmax": 600,
"cur": ["USD"],
"test": 1
}

The answer is a bid response with 200, or 204 with no bid.