<!-- https://docs.youtarget.com/rtb/en/ssp/json-feed.html -->

# JSON feed specification

> How to get push and popunder ads from us via the JSON feed: endpoint, request parameters, response fields, impression and click counting, payouts and examples.

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: [CPM](https://docs.youtarget.com/rtb/en/glossary/cpm.md) 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

- [Push](./feed-examples/push.md): `format=push` or no parameter. There is also a variant with [impression counted on image load](./feed-examples/push.md#response-with-impression-counted-on-image-load).
- [Popunder](./feed-examples/popunder.md): `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.

```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 floor](https://docs.youtarget.com/rtb/en/glossary/bid-floor.md)): 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](#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 `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.

| 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 sync](https://docs.youtarget.com/rtb/en/glossary/cookie-sync.md). 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 | [Zone](https://docs.youtarget.com/rtb/en/glossary/zone.md) 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: 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.

| 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 `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 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_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:

- [Push](./feed-examples/push.md)
- [Popunder](./feed-examples/popunder.md)
