Bid request
Endpoint
Section titled “Endpoint”POST https://api.elo.ad/v1/rtb/bidSend an OpenRTB 2.6 bid request as JSON, with Content-Type: application/json.
Authentication
Section titled “Authentication”Send your publisher API key in the Authorization header:
Authorization: Bearer $ELO_PUBLISHER_API_KEYThe 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.
Fields Elo reads
Section titled “Fields Elo reads”Elo reads only the fields below and ignores the rest, so you can send a full OpenRTB 2.6 request as it is.
| Field | Required | Use |
|---|---|---|
id | yes | Echoed in the bid response. |
imp | yes | At least one impression. Only imp[0] is read. |
imp[0].id | yes | Echoed as the bid’s impid. |
imp[0].native.request | yes | The 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].tagid | no | Stored for reporting. |
imp[0].bidfloor | no | The floor CPM. Elo does not bid when the floor is above its price. Default 0. |
imp[0].bidfloorcur | no | Must be USD. Default USD. |
imp[0].ext.elo | no | Context that has no standard field, such as intent. See Context. |
site or app | no | keywords, 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.content | no | title, keywords, kwarray and cat are matched on. |
user.keywords, user.kwarray | no | Matched on. |
device.geo.country | yes, to get a bid | The user’s country, as ISO 3166-1 alpha-3 (USA) or alpha-2 (US). |
regs.coppa | no | Elo does not bid when it is 1. |
tmax | no | The time you wait for an answer, in milliseconds. |
test | no | 1 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.
Context
Section titled “Context”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["trail running", "shoes"]intent"buy running shoes"topic"marathon training"categories["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.
Native request
Section titled “Native request”Elo answers these Native 1.2 assets:
| Asset | Answer |
|---|---|
title | The 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.
Example
Section titled “Example”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.jsonbid-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.