Skip to content

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 cnt ads 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 cpc field is the ad price: per click with CPC, per 1,000 impressions with CPM (despite the name).

Supported formats ​

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.

text
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 ip and ua parameters.
  • URL-encode the values: ua and lang contain spaces, commas and semicolons.
  • There is no test mode.

What the manager configures:

  • Currency and pricing model: the units of floor and cpc.
  • Enabled formats: which format values return ads.
  • Minimum price (bid floorThe minimum bid below which an impression is not sold.): the floor request 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 ​

CodeMeaningWhat to do
200There is an ad; the body is a JSON arrayShow the ad and call the impression counting URLs
204No ad, no bodyShow your own ad or nothing
400No id, unknown format value, or req_id is not a UUIDFix the request
403The integration is inactiveContact the manager
404Unknown idCheck the URL against the one the manager sent
500Internal errorRetry 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 nbr field.
  • Parse the body as JSON based on the 200 code, not on the Content-Type header.

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.

ParameterRequiredDescription
Integration
idyesIntegration ID, 32 hex characters, already in the URL. Missing: 400; unknown: 404
formatonly for popunderpush (default) or pop
User and device
ipyesThe user's IPv4 or IPv6: country, city, carrier, connection type
uayesThe User-Agent of the user's browser: device, OS, browser
langrecommendedLanguage code or Accept-Language, for example de-DE,de;q=0.9; reduced to the base code
sec-ch-ua-modelnoClient Hint for the device model; quotes are allowed
sec-ch-ua-platformnoClient Hint for the OS
sec-ch-ua-platform-versionnoClient Hint for the OS version
user_idnoThe user ID on your side
user_buyer_uidnoOur 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_daysrecommended for pushHow many days ago the user subscribed to push, an integer
sub_datenoSubscription date, Unix time in seconds. If both are passed, we use sub_days
Placement
placement_tag_idyesZoneA 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_idnoWebsite or app ID
context_typeno2 for app; any other value, or no value, means website
domainyes, for websitesDomain without the scheme
bundleyes, for appsApp bundle ID
catnoComma-separated IAB categories of the placement content
ratingnoContent age rating; used when selecting creatives
subidnoYour source subid: statistics and subid filters
Restrictions and service parameters
bcatnoBlocked IAB categories, comma-separated
badvnoBlocked advertiser domains, comma-separated
floornoMinimum price in cpc units, a number with a decimal point. Overrides the bid floor from the settings; an invalid value is ignored
cntnoHow many ads to return, from 1 to 10. Defaults to 1; 0 and non-numeric values also give 1
req_idnoYour 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 "".

FieldFormatDescription
idpush, popunderAd ID, a UUID. It also appears in all URLs of the ad
impidpush, popunderPosition in the response: "1", "2"
cridpush, popunderCreative ID
campaign_idpush, popunderCampaign ID, a number
categorypush, popunderIAB category of the creative or ""
titlepushNotification title
textpushNotification text
image_urlpush, popunderPush: large image or impression counting URL. Popunder: service field, no need to load it
icon_urlpushIcon
click_urlpush, popunderPush: click URL. Popunder: the page to open in the popunder window
nurlpush, popunderWin notice
burlpush, popunderBilling notice
cpcpush, popunderPrice in the account currency: per click with CPC, per 1,000 impressions with CPM
  • The creative macros {city} and {date} are already expanded: show title and text as they are.
  • floor uses the same units as cpc. Example: an integration in USD with CPM and floor=0.5 means at least $0.50 per 1,000 impressions.

Impression counting and payouts ​

The manager chooses the impression counting method separately for each format.

OptionWhen the impression is countedWhat you do
By nurlWhen nurl is calledCall nurl when the ad is shown
By burlWhen burl is calledCall burl when the ad is shown
By image, or viewable impression by image (push)When image_url is loadedLoad image_url from the user's device at the moment of the impression. The URL counts the impression and redirects (302) to the image
PopunderWhen click_url is openedOpen 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 nurl and burl with 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_url and icon_url from 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 modelBillable eventWhat we pay for
CPCnot setClick: opening click_url
CPMby nurl / by burlCalling nurl / burl
CPMby impressionPush: loading the impression counting URL from image_url or icon_url. Popunder: opening click_url
CPM, popundernot setOpening 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_url opens 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:

© Youtarget