JSON feed specification
The JSON feed serves Youtarget ads without OpenRTB: a GET request with parameters in the URL, and a JSON array of ready-to-show ads in response.
Specifications
- Request: HTTPS GET, all data in query parameters. No body, no compression needed.
- Response: a JSON array of up to
cntads in descending price order, or HTTP 204 with no body. - Formats: push and popunder, one format per request.
- Currency: your account currency; pricing model: CPMThe price per thousand impressions. or CPC. Both are set when you connect and are not passed in the request or the response.
- The
cpcfield is the ad price: per click with CPC, per 1,000 impressions with CPM (despite the name).
Supported formats
- Push:
format=pushor no parameter. There is also a variant with impression counted on image load. - Popunder:
format=pop.
The format must be enabled for the integration, otherwise 204. native, banner, video and audio always get 204; any other format value gets 400.
TIP
Without format=pop you get push, even if the placement is a popunder.
Connecting
Your account manager sets up the integration and sends you the integration URL with your integration ID in the id parameter. You add the other parameters. The URLs on this page are placeholders.
https://feed.example.com/bid?id=9b2f4c1e7a3d4e5f8a6b0c1d2e3f4a5b- POST is also accepted, but the body is not read: pass the data in the URL anyway.
- No headers are needed: pass the user's IP and User-Agent in the
ipanduaparameters. - URL-encode the values:
uaandlangcontain spaces, commas and semicolons. - There is no test mode.
What the manager configures:
- Currency and pricing model: the units of
floorandcpc. - Enabled formats: which
formatvalues return ads. - Minimum price (bid floorThe minimum bid below which an impression is not sold.): the
floorrequest parameter overrides it. - Response time and requests per second limit: you cannot pass them in the request; if the auction runs out of time or the limit is exceeded, the response is 204.
- Impression counting method and billable event: which URLs from the response to call, see Impression counting and payouts. Find them out before launch: if you call the wrong URL, impressions are not counted.
The feed has no consent parameters (GDPR, CCPA), no COPPA flag and no schain. If your traffic requires them, discuss it with the manager before connecting.
Response codes
| Code | Meaning | What to do |
|---|---|---|
| 200 | There is an ad; the body is a JSON array | Show the ad and call the impression counting URLs |
| 204 | No ad, no body | Show your own ad or nothing |
| 400 | No id, unknown format value, or req_id is not a UUID | Fix the request |
| 403 | The integration is inactive | Contact the manager |
| 404 | Unknown id | Check the URL against the one the manager sent |
| 500 | Internal error | Retry later |
Reasons for 204: no ads above floor, the format is not enabled or not supported, the auction ran out of time, the request limit is exceeded, or the request was cut off by the integration filters or the traffic quality check.
- Handle a 200 response with an empty array
[]as 204. - The response does not give the reason: there is no
nbrfield. - Parse the body as JSON based on the 200 code, not on the
Content-Typeheader.
Request parameters
"Yes" means that without the parameter the request gets 400 or almost no one will buy it: without ip there is no geo, without ua no device, and without the zone ID and domain advertiser filters don't work. Technically the server rejects only a request without id. "Recommended" means fewer bids without it. Unknown parameters are ignored.
| Parameter | Required | Description |
|---|---|---|
| Integration | ||
id | yes | Integration ID, 32 hex characters, already in the URL. Missing: 400; unknown: 404 |
format | only for popunder | push (default) or pop |
| User and device | ||
ip | yes | The user's IPv4 or IPv6: country, city, carrier, connection type |
ua | yes | The User-Agent of the user's browser: device, OS, browser |
lang | recommended | Language code or Accept-Language, for example de-DE,de;q=0.9; reduced to the base code |
sec-ch-ua-model | no | Client Hint for the device model; quotes are allowed |
sec-ch-ua-platform | no | Client Hint for the OS |
sec-ch-ua-platform-version | no | Client Hint for the OS version |
user_id | no | The user ID on your side |
user_buyer_uid | no | Our user ID from cookie syncMatching user IDs between two ad systems.. Synonym: user_buyer_id; if both are passed, we use user_buyer_uid |
sub_days | recommended for push | How many days ago the user subscribed to push, an integer |
sub_date | no | Subscription date, Unix time in seconds. If both are passed, we use sub_days |
| Placement | ||
placement_tag_id | yes | ZoneA specific ad slot on a site or in an app, for example a block on a site page. ID: statistics and zone filters work by it |
context_id | no | Website or app ID |
context_type | no | 2 for app; any other value, or no value, means website |
domain | yes, for websites | Domain without the scheme |
bundle | yes, for apps | App bundle ID |
cat | no | Comma-separated IAB categories of the placement content |
rating | no | Content age rating; used when selecting creatives |
subid | no | Your source subid: statistics and subid filters |
| Restrictions and service parameters | ||
bcat | no | Blocked IAB categories, comma-separated |
badv | no | Blocked advertiser domains, comma-separated |
floor | no | Minimum price in cpc units, a number with a decimal point. Overrides the bid floor from the settings; an invalid value is ignored |
cnt | no | How many ads to return, from 1 to 10. Defaults to 1; 0 and non-numeric values also give 1 |
req_id | no | Your request ID as a UUID, otherwise 400. Without it, we generate our own |
The zone ID is the first non-empty value other than 0 from placement_tag_id, context_id, subid, in that order.
Response
All fields are always present; an empty value is "".
| Field | Format | Description |
|---|---|---|
id | push, popunder | Ad ID, a UUID. It also appears in all URLs of the ad |
impid | push, popunder | Position in the response: "1", "2" |
crid | push, popunder | Creative ID |
campaign_id | push, popunder | Campaign ID, a number |
category | push, popunder | IAB category of the creative or "" |
title | push | Notification title |
text | push | Notification text |
image_url | push, popunder | Push: large image or impression counting URL. Popunder: service field, no need to load it |
icon_url | push | Icon |
click_url | push, popunder | Push: click URL. Popunder: the page to open in the popunder window |
nurl | push, popunder | Win notice |
burl | push, popunder | Billing notice |
cpc | push, popunder | Price in the account currency: per click with CPC, per 1,000 impressions with CPM |
- The creative macros
{city}and{date}are already expanded: showtitleandtextas they are. flooruses the same units ascpc. Example: an integration in USD with CPM andfloor=0.5means at least $0.50 per 1,000 impressions.
Impression counting and payouts
The manager chooses the impression counting method separately for each format.
| Option | When the impression is counted | What you do |
|---|---|---|
By nurl | When nurl is called | Call nurl when the ad is shown |
By burl | When burl is called | Call burl when the ad is shown |
| By image, or viewable impression by image (push) | When image_url is loaded | Load image_url from the user's device at the moment of the impression. The URL counts the impression and redirects (302) to the image |
| Popunder | When click_url is opened | Open click_url in a popunder window in the user's browser |
Rules for calling the URLs:
- Call the URLs exactly as they came: they contain no macros, and the notifications don't carry a price.
- Call
nurlandburlwith GET (POST is also accepted), from your server or from the browser. - A repeated call returns 200, but is not counted a second time: retries are safe.
- An invalid, modified or expired URL returns 400. The URLs are valid for a limited time: call them at the moment of the impression and the click.
- Load
image_urlandicon_urlfrom the URLs in the response; don't replace or cache them: for some ads, loading them is the impression.
What we pay for (the event price is cpc from the response):
| Pricing model | Billable event | What we pay for |
|---|---|---|
| CPC | not set | Click: opening click_url |
| CPM | by nurl / by burl | Calling nurl / burl |
| CPM | by impression | Push: loading the impression counting URL from image_url or icon_url. Popunder: opening click_url |
| CPM, popunder | not set | Opening click_url |
For push with CPM, the billable event must be set; if the manager has not specified it, ask them to choose one.
Click
click_urlopens in the user's browser: for push, on a click on the notification; for popunder, right at the impression.- We redirect to the landing page with a 302 code or an HTML page that redirects with JavaScript or meta refresh, so a server-side request won't work.
- We check clicks for traffic quality: open the URL in the browser of the user who saw the ad.
Examples
Requests and responses for each format: