Bid Endpoint
One GET per impression opportunity. We answer with the ad that won the auction,
or with 204 when nothing bid.
GET /v1/feed/{feed_key} HTTP/1.1
Host: dsp.xml.adon3.com
Accept: application/json
Accept-Encoding: gzip
{feed_key} identifies your supply endpoint and its supply type. POST is not
supported. Every parameter below is a query parameter and must be URL-encoded.
Parameter names and enumerated values on this page are provisional while version 1.0 is finalised. Confirm anything you are about to hard-code with the adon3 integration office.
Required parameters
| Field | Type | Req. | Notes |
|---|---|---|---|
ip | string | yes | Visitor IPv4 or IPv6. Must be the visitor's address, not your server's. |
ua | string | yes | Full, unmodified user agent, URL-encoded. |
We reject a call with 400 when either is missing. A truncated or synthesised
user agent is worse than useless, because it passes validation and then loses you
the targeting that pays best.
Identification
| Field | Type | Req. | Notes |
|---|---|---|---|
subid | string | no | Your placement, zone or publisher token. Up to 64 characters, [A-Za-z0-9_.-]. |
rid | string | no | Your request id. Used for deduplication and for support lookups. |
uid | string | no | Stable visitor identifier, hashed on your side. Improves frequency capping. |
referrer | string | no | Page or app referrer URL. |
lang | string | no | BCP-47 language tag, for example en-GB. Falls back to what we infer. |
subid is the dimension every report breaks down by, so a scheme you can still
read six months from now is worth ten minutes today. Sending one subid for all
traffic works, and tells you nothing.
Context and targeting
| Field | Type | Req. | Notes |
|---|---|---|---|
cat | string | no | IAB content categories, comma-separated, for example IAB13,IAB19. |
keyword | string | no | Context keywords, comma-separated. Up to 20. |
n | int | no | Ads requested, 1 to 5. Default 1. We may return fewer. |
min_price | float | no | Floor in USD CPC. Bids below it are dropped rather than returned. |
test | int | no | 1 runs the auction without billing and without counting. Default 0. |
Setting n above 1 is only useful when you have somewhere to show the extras.
Requesting five ads and showing one depresses your fill quality score.
Pop parameters
Accepted only on feed keys whose supply type is pop.
| Field | Type | Req. | Notes |
|---|---|---|---|
pop_type | string | no | under or over. Default under. |
Push parameters
Accepted only on feed keys whose supply type is push. On any other key they
return 403.
| Field | Type | Req. | Notes |
|---|---|---|---|
img_size | string | no | Hero image size as WxH, for example 492x328. Default 360x240. |
icon_size | string | no | Icon size as WxH, for example 192x192. Default 192x192. |
sub_age | int | no | Days since the visitor subscribed. Older lists price differently. |
If you cannot render an image at the size you asked for, ask for the size you can render. We select creatives against these values, and a mismatch shows up as a low click-through rate rather than as an error.
Client hints
Modern browsers reduce the user agent, so send the hints when you have them. Each maps to the header of the same name.
| Field | Type | Req. | Notes |
|---|---|---|---|
ch_ua | string | no | Sec-CH-UA value. |
ch_platform | string | no | Sec-CH-UA-Platform, for example Android. |
ch_platform_ver | string | no | Sec-CH-UA-Platform-Version. |
ch_mobile | int | no | Sec-CH-UA-Mobile, 1 or 0. |
ch_model | string | no | Sec-CH-UA-Model. |
Response control
| Field | Type | Req. | Notes |
|---|---|---|---|
format | string | no | json (default) or xml. |
A complete request
curl -sS -G 'https://dsp.xml.adon3.com/v1/feed/9862b397ba3320149b94a05079597eb3' \
--compressed \
--data-urlencode 'ip=203.0.113.44' \
--data-urlencode 'ua=Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36' \
--data-urlencode 'subid=zone-4471' \
--data-urlencode 'rid=8f2a1c30-6b4e-4d9a-9f11-2c7e3b5a8d40' \
--data-urlencode 'uid=3d9f7a2b6c1e' \
--data-urlencode 'referrer=https://gazette.example.com/markets/open-exchange' \
--data-urlencode 'lang=en-US' \
--data-urlencode 'cat=IAB13' \
--data-urlencode 'ch_platform=Android' \
--data-urlencode 'ch_mobile=1' \
--data-urlencode 'n=1'
Status codes
| Status | Meaning |
|---|---|
200 | A fill. Body carries one or more ads. |
204 | No fill. Empty body. Normal and expected. |
400 | A required parameter is missing or malformed. |
401 | Unknown or revoked feed key. |
403 | Parameters do not match the key's supply type, or the account is suspended. |
429 | Above the provisioned request rate for this key. |
503 | Shedding load. Treat as a no-fill and move on. |
Full bodies and error codes are on Status & Errors.
Next: Response Formats.