Response Formats

A fill is 200 with a body carrying one or more ads. The default body is JSON, and format=xml returns the same fields as an XML document. Nothing is lost either way, so pick whichever your stack parses more cheaply.

Envelope fields

Field	Type	Notes
`rid`	string	The `rid` you sent, or one we generated when you did not.
`cur`	string	Currency of every `price` in the body. `USD` at launch.
`ads`	array	One entry per ad. Never empty on a `200`.

Common ad fields

Present for every supply type. Only url, price and imp_url are guaranteed on every ad.

Field	Type	Notes
`cid`	string	Creative id, when one is exposed for the campaign. May be absent, so do not key on it. Quote it in support requests about a specific ad.
`url`	string	Click destination, wrapped in our tracker. Serve it unmodified.
`price`	string	CPC in `cur`, as a decimal string. Four decimal places on direct link and push, up to six on pop.
`imp_url`	string	Impression notice. Fire once, when the ad is shown.
`exp`	int	Seconds the `url` stays valid. `900` unless stated otherwise.

price is a string rather than a float on purpose. CPC values run to four decimal places, and to six on pop, where the per-click values are small enough to need them. Rounding either through a binary float is the most common cause of revenue figures that disagree with ours by a fraction of a cent per click.

Direct link

A link key returns the common fields and nothing else. Send the visitor straight to url.

JSON

{
  "rid": "8f2a1c30-6b4e-4d9a-9f11-2c7e3b5a8d40",
  "cur": "USD",
  "ads": [
    {
      "cid": "cr-88213",
      "url": "https://t9m6ci.xml.adon3.com/track/click?aid=7c41b0e9-2f8a-4d61-9c33-1ab5e77d0244&url=QzE4YjJhLTQ0NzEtb3BhcXVlLXRhcmdldA&did=26cbfffc-5313-4a6e-901f-556e056034f7&ctx=u77zOyuAFBNzUKZmkr2H7UN4Qxm_Wh8OV31KIkPl2gYgZJrClKtp2-3x",
      "price": "0.0142",
      "imp_url": "https://t9m6ci.xml.adon3.com/v1/imp/tj24Aw45P7AnbRSKRtYGQH-3mrKBh8VJtdrqd3DJiAxRL610ngFGm3pe",
      "exp": 900
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<response rid="8f2a1c30-6b4e-4d9a-9f11-2c7e3b5a8d40" cur="USD">
  <ad>
    <cid>cr-88213</cid>
    <url>https://t9m6ci.xml.adon3.com/track/click?aid=7c41b0e9-2f8a-4d61-9c33-1ab5e77d0244&amp;url=QzE4YjJhLTQ0NzEtb3BhcXVlLXRhcmdldA&amp;did=26cbfffc-5313-4a6e-901f-556e056034f7&amp;ctx=u77zOyuAFBNzUKZmkr2H7UN4Qxm_Wh8OV31KIkPl2gYgZJrClKtp2-3x</url>
    <price>0.0142</price>
    <imp_url>https://t9m6ci.xml.adon3.com/v1/imp/tj24Aw45P7AnbRSKRtYGQH-3mrKBh8VJtdrqd3DJiAxRL610ngFGm3pe</imp_url>
    <exp>900</exp>
  </ad>
</response>

url is a tracking URL carrying its parameters in the query string, and its host is not the host you sent the feed request to. Serve both url and imp_url exactly as returned. Rebuilding either from parts, or dropping a parameter you do not recognise, breaks attribution and costs you the click.

Element content is XML-escaped, so every & between those query parameters arrives as & inside url and imp_url. Unescape before you redirect, or the destination will not resolve.

Pop

A pop key returns the common fields plus the two below.

Field	Type	Notes
`pop_type`	string	`under` or `over`, matching what the buyer purchased.
`freq_cap`	int	Suggested maximum pops per visitor per day. `0` means uncapped.

price carries up to six decimal places on this supply type, rather than the four you see on direct link and push. Parse the full string. Truncating it to four places drops real revenue on every click.

JSON

{
  "rid": "5c72d19b-8043-4a7e-b06f-2ad9317c4e85",
  "cur": "USD",
  "ads": [
    {
      "cid": "cr-40217",
      "url": "https://t9m6ci.xml.adon3.com/track/click?aid=a52feb70-fb9d-433d-be32-d5d08b2e47a9&url=UDQwMjE3LTg4MjEtb3BhcXVlLXRhcmdldA&did=26cbfffc-5313-4a6e-901f-556e056034f7&ctx=-4PH6MXtIPYgVcWCCL-ehBLc_FpeOBTtRk8dsZP6cAEAKXJNwrvHAmrj",
      "price": "0.003825",
      "imp_url": "https://t9m6ci.xml.adon3.com/v1/imp/RtYGQH-3mrKBh8VJtdrqd3DJiAxRL610ngFGm3peT6uk0yaDB0oohNOh",
      "exp": 900,
      "pop_type": "under",
      "freq_cap": 3
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<response rid="5c72d19b-8043-4a7e-b06f-2ad9317c4e85" cur="USD">
  <ad>
    <cid>cr-40217</cid>
    <url>https://t9m6ci.xml.adon3.com/track/click?aid=a52feb70-fb9d-433d-be32-d5d08b2e47a9&amp;url=UDQwMjE3LTg4MjEtb3BhcXVlLXRhcmdldA&amp;did=26cbfffc-5313-4a6e-901f-556e056034f7&amp;ctx=-4PH6MXtIPYgVcWCCL-ehBLc_FpeOBTtRk8dsZP6cAEAKXJNwrvHAmrj</url>
    <price>0.003825</price>
    <imp_url>https://t9m6ci.xml.adon3.com/v1/imp/RtYGQH-3mrKBh8VJtdrqd3DJiAxRL610ngFGm3peT6uk0yaDB0oohNOh</imp_url>
    <exp>900</exp>
    <pop_type>under</pop_type>
    <freq_cap>3</freq_cap>
  </ad>
</response>

A pop counts as shown once the window has opened and loaded. Fire imp_url at that point, not when you decide to open it, since blocked pops that never render are the largest single source of impression discrepancy on this supply type.

Push

A push key returns the common fields plus the notification payload.

Field	Type	Notes
`title`	string	Notification title. Up to 64 characters.
`text`	string	Notification body. Up to 160 characters.
`image`	string	Hero image at the `img_size` you requested, or the default.
`icon`	string	Icon at the `icon_size` you requested, or the default.

JSON

{
  "rid": "a7f14e60-9b23-4c58-8d71-e0c4f2a6b913",
  "cur": "USD",
  "ads": [
    {
      "cid": "cr-90714",
      "url": "https://t9m6ci.xml.adon3.com/track/click?aid=3b90714d-4471-4c0a-9f52-8e6d1a7c4b03&url=UDA5MDcxNC00NDcxLW9wYXF1ZS10YXJnZXQ&did=26cbfffc-5313-4a6e-901f-556e056034f7&ctx=ZJrClKtp2-3xEBsWJVLHBWFWTh54P0F9Hm3DjwP9F02y0sKnnCCcNu9Z",
      "price": "0.0310",
      "imp_url": "https://t9m6ci.xml.adon3.com/v1/imp/P7AnbRSKRtYGQH-3mrKBh8VJtdrqd3DJiAxRL610ngFGm3peT6uk0yaD",
      "exp": 900,
      "title": "Your delivery is waiting",
      "text": "Confirm the address and it ships today.",
      "image": "https://cdn.adon3-ads.com/i/90714/492x328.jpg",
      "icon": "https://cdn.adon3-ads.com/i/90714/192x192.png"
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<response rid="a7f14e60-9b23-4c58-8d71-e0c4f2a6b913" cur="USD">
  <ad>
    <cid>cr-90714</cid>
    <url>https://t9m6ci.xml.adon3.com/track/click?aid=3b90714d-4471-4c0a-9f52-8e6d1a7c4b03&amp;url=UDA5MDcxNC00NDcxLW9wYXF1ZS10YXJnZXQ&amp;did=26cbfffc-5313-4a6e-901f-556e056034f7&amp;ctx=ZJrClKtp2-3xEBsWJVLHBWFWTh54P0F9Hm3DjwP9F02y0sKnnCCcNu9Z</url>
    <price>0.0310</price>
    <imp_url>https://t9m6ci.xml.adon3.com/v1/imp/P7AnbRSKRtYGQH-3mrKBh8VJtdrqd3DJiAxRL610ngFGm3peT6uk0yaD</imp_url>
    <exp>900</exp>
    <title>Your delivery is waiting</title>
    <text>Confirm the address and it ships today.</text>
    <image>https://cdn.adon3-ads.com/i/90714/492x328.jpg</image>
    <icon>https://cdn.adon3-ads.com/i/90714/192x192.png</icon>
  </ad>
</response>

Render title and text as sent. Truncating them mid-word is the fastest way to lose the click, and rewriting them puts the creative out of line with what was approved in review.

Serving rules

Do not modify url. Every identifier the click needs is inside it. Appending your own parameters is fine, rewriting the host or the path is not.
Fire imp_url once per shown ad. Not per request, and not per click.
Respect exp. A cached ad served after it expires produces a click that resolves to a dead redirect and is not billable.
Match the scheme of your page. We return HTTPS URLs by default and they work on HTTP pages, but an HTTP page embedding HTTPS assets in a mixed-content policy will drop them.
Never cache a fill across visitors. Ads are selected for the ip, ua and uid you sent. Replaying one to a different visitor counts as click fraud on our side of the ledger, however innocently it happens.

No fill

204 No Content with an empty body. There is no envelope and no error to parse. Treat it as a normal outcome, fall back to whatever you would otherwise show, and do not retry, because the same call returns the same answer.

Next: Status & Errors.