Developer guide

Three ways to connect

Demand partners bid in one of two ways. Publishers who want their figures in their own systems use the third.

Both bidding routes meet in the same auction, next to Google Ad Exchange. The highest price is the one shown, whoever it comes from.

What we serve

Partner bidding is open on display placements. The other formats on our publishers' pages run through Google Ad Manager's own formats and are not open to partner bids today.

The sizes you will see most are 300×250, 336×280, 728×90, 970×250, 300×600, 320×100 and 320×50. Each request lists exactly what that placement takes, and that list is the only authority.

• Web only. Desktop and mobile browsers. No in-app inventory.
• US dollars only. Floors, bids and settlement are in USD. A bid in another currency is dropped.
• Refresh. A placement that stays in view can refresh. Every refresh is a new auction with a new request.
• Reviewed sites. A site serves nothing until our team has approved it.

How the auction runs

1. A placement is about to loadThe tag on the publisher's page asks our server for bids on it.
2. Every partner is asked at onceOne request each, sent in parallel, each with its own tmax.
3. Answers are collectedA late answer, an error or an empty one is a no-bid. Nothing is retried.
4. The best price goes forwardThe highest valid bid among partners competes with Google Ad Exchange and the Prebid bidders.
5. The winner is shown and toldIf it is yours, we render your markup and call your notice addresses.

It is a first-price auction (at is 1): if you win, you pay what you bid. To compete inside the ad server a price is rounded down to a price point: every cent up to $1, every 5 cents up to $3, every 25 cents up to $10 and every dollar up to $20. A bid above $20 competes as $20. The price we report back to you is always your own bid, unrounded.

The bid request

A POST to your endpoint with a JSON body. One request carries one impression.

POST /openrtb HTTP/1.1
Host: bid.partner.example
Content-Type: application/json
x-openrtb-version: 2.5
X-Api-Key: the-value-you-gave-us

{
  "id": "5f0c2a9e41b7d3c86a12e0f4",
  "imp": [
    {
      "id": "1",
      "tagid": "vfx-article-top",
      "banner": {
        "w": 300,
        "h": 250,
        "format": [
          { "w": 300, "h": 250 },
          { "w": 336, "h": 280 }
        ]
      },
      "secure": 1,
      "bidfloorcur": "USD",
      "bidfloor": 0.25
    }
  ],
  "site": {
    "id": "example-news",
    "domain": "example.com",
    "page": "https://example.com/world/a-story-worth-reading"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36",
    "ip": "203.0.113.24",
    "language": "en"
  },
  "cur": ["USD"],
  "at": 1,
  "tmax": 800
}

Your bid response

Answer 200 with a standard bid response to bid. To pass, answer 204 with no body, which is the cheapest thing for both of us.

{
  "id": "5f0c2a9e41b7d3c86a12e0f4",
  "bidid": "b-7741",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "seat-42",
      "bid": [
        {
          "id": "1",
          "impid": "1",
          "price": 2.4,
          "w": 300,
          "h": 250,
          "adid": "cr-889",
          "crid": "889",
          "adomain": ["advertiser.example"],
          "adm": "<a href=\"https://click.partner.example/c?b=${AUCTION_BID_ID}\" target=\"_blank\" rel=\"noopener\"><img src=\"https://cdn.partner.example/889.jpg\" width=\"300\" height=\"250\" alt=\"\"></a>",
          "nurl": "https://win.partner.example/w?p=${AUCTION_PRICE}&id=${AUCTION_ID}",
          "burl": "https://bill.partner.example/b?p=${AUCTION_PRICE}&imp=${AUCTION_IMP_ID}"
        }
      ]
    }
  ]
}

A bid is accepted when all of this is true:

• The status is 200, the body is JSON with a seatbid array, and it arrived within tmax.
• price is a number above zero, at or above your floor, and no more than $200 CPM.
• adm is a non-empty string of HTML.
• w and h are one of the sizes in the request. Leave them out and we take the first size.
• cur is USD or left out.

We do not send loss notices. If you hear nothing after bidding, you did not win or the creative was never shown.

Macros and notices

These are replaced in adm, nurl and burl:

When the notices are called. Not when you win the auction, but when your creative is placed on the page. At that moment our server calls nurl and burl with a GET, once each. Most winning bids are shown within a second or two.

• Bill on the notice, never on the bid response. A bid that was not shown is not notified and is not owed.
• Each address must start with http:// or https:// and be no longer than 2,000 characters after the macros are filled in.
• We wait 1.5 seconds for your answer and do not retry. Answer fast and with any 2xx.
• A creative shown more than 30 minutes after the bid is not notified. This is rare; it is a tab left open in the background.
• The calls come from our server, not from the visitor's browser, so they carry no visitor cookies. For a browser-side count, put your own pixel in adm.

Creative rules

Your markup is written into a sandboxed frame of exactly the size you bid. The frame allows scripts and allows a click to open a new tab. It does not give access to the publisher's page, its cookies or its storage.

<!-- Everything over https. The click opens a new tab. -->
<a href="https://click.partner.example/c?b=${AUCTION_BID_ID}" target="_blank" rel="noopener">
  <img src="https://cdn.partner.example/889.jpg" width="300" height="250" alt="">
</a>
<img src="https://px.partner.example/i?p=${AUCTION_PRICE}" width="1" height="1" alt="" style="position:absolute">

• HTML only. No VAST, no native JSON, no MRAID.
• HTTPS only. One asset over plain HTTP and the browser blocks it.
• Open clicks in a new tab with target="_blank". Navigating the publisher's page from inside the frame is blocked.
• Stay inside the frame. No expanding, no covering the page, no resizing.
• Nothing the visitor did not ask for. No redirects, no pop-ups or downloads without a click, no sound until a click.
• No reading of the page. The frame has its own empty origin, so cookies and local storage from your own domain are not available inside it either.

A creative that breaks these rules gets its partner switched off until it is fixed. Publishers can report a creative to us, and we will come to you with the page, the time and the price.

Backfill requests

Some sites ask partners only after Google Ad Exchange has returned nothing for a placement. Those requests come to the same endpoint and differ in a few ways. If any of them is a problem, say so and we keep you on the standard requests only.

Test and go live

1. Send us your details. The list under Before you start.
2. We add your endpoint. From that moment you receive real bid requests. Answer 204 until you are ready to bid.
3. Check what arrives. Confirm that the body parses, the sizes are ones you buy and the floor is the one you gave us.
4. Bid on a page we agree. We watch one of your creatives render and confirm both notices reached you with the right price.
5. Compare the first full day. Your billed impressions against our count of wins. Tell us if they are more than a few percent apart, before volume grows.

If you allow traffic by IP address, ask us for the addresses our requests come from.

What we need from you

• Your adapter's name in the Prebid.js repository. It has to be an official adapter that works on Prebid 11.
• Your bidder code, as Prebid knows it.
• One set of parameters. See the note below.
• What you buy: display sizes, and native if we have agreed it.
• Your ads.txt lines for our publishers. See ads.txt and sellers.json.

How your adapter is called

// What we register for each placement. You do not write this; it is here so you know what your adapter receives.
pbjs.addAdUnits([{
  code: "vfx-article-top",                                  // the placement's element id
  mediaTypes: { banner: { sizes: [[300, 250], [336, 280]] } },
  bids: [
    { bidder: "yourBidder", params: { networkId: "12345" } }   // the one set of parameters you give us
  ]
}]);

pbjs.setConfig({ bidderTimeout: 1200 });

• Timeout. bidderTimeout is 1,200 ms unless we have agreed another value. A bid that arrives later is ignored.
• Currency. Bid in USD. Prebid's currency module is not in the build, so nothing is converted, and on most sites a bid in another currency is dropped.
• Price. Your bid is rounded down to a price point to compete in the ad server, the same ladder as for OpenRTB on most sites. Prebid reports your own bid price back to you.
• Winning. Prebid tells your adapter in the usual way (onBidWon and your creative's own pixels). We add nothing of our own to it.
• Creative. Rendered in a sandboxed frame. The creative rules are the same.
• Refresh. A refreshed placement runs a new Prebid auction.

Test and go live

1. Send us your details. The list under What we need from you.
2. We add your adapter to the build and your bidder to our list, switched off.
3. We switch you on. Your adapter starts receiving bid requests from every site that runs Prebid.
4. Check a live page together. Add ?pbjs_debug=true to a page's address and Prebid logs your requests and bids to the browser console.
5. Compare the first full day. Your paid impressions against the wins we count.

Keys and your first call

Make your key on the Reporting API page of the dashboard. It is shown once, so copy it into your server's secrets when you make it. There is one key for an account; making a new one stops the old one at once.

Send the key in a header on every request:

export VFX_API_KEY="vfx_your_key_here"

curl "https://visionforgex.com/api/v1/" \
  -H "Authorization: Bearer $VFX_API_KEY"

{
    "data": {
        "account": "Example Media",
        "email": "[email protected]",
        "access": "on",
        "sites": 2,
        "limits": {
            "requests_per_minute": 60,
            "requests_per_day": 5000,
            "max_days_per_request": 90
        },
        "endpoints": {
            "sites": "https://visionforgex.com/api/v1/sites/",
            "reports": "https://visionforgex.com/api/v1/reports/"
        }
    },
    "meta": {
        "version": "v1",
        "data_updated_at": "2026-10-06T21:40:12Z",
        "docs": "https://visionforgex.com/developers/#reporting-api"
    }
}

• Authorization: Bearer <key> is the header to use. X-API-Key: <key> works too, for tools that cannot set the first one.
• A key in the address (?key=…) is refused. Addresses end up in logs.
• Call from a server. A key in a web page or a mobile app can be read by anyone who opens it, and the API does not answer browser cross-origin requests.
• Every address is GET only, over HTTPS, and ends with a slash.

Reports

GEThttps://visionforgex.com/api/v1/reports/

curl "https://visionforgex.com/api/v1/reports/?from=2026-09-30&to=2026-10-06&group_by=date,domain" \
  -H "Authorization: Bearer $VFX_API_KEY"

<?php
$url = 'https://visionforgex.com/api/v1/reports/?' . http_build_query([
    'from' => '2026-09-30',
    'to' => '2026-10-06',
    'group_by' => 'date,domain',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('VFX_API_KEY')],
    CURLOPT_TIMEOUT => 20,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$report = json_decode((string) $body, true);
if ($status !== 200) {
    throw new RuntimeException($report['error']['message'] ?? 'The request failed');
}

foreach ($report['data'] as $row) {
    echo $row['date'], ' ', $row['domain'], ' ', $row['revenue'], "\n";
}

import os
import requests

response = requests.get(
    "https://visionforgex.com/api/v1/reports/",
    headers={"Authorization": f"Bearer {os.environ['VFX_API_KEY']}"},
    params={"from": "2026-09-30", "to": "2026-10-06", "group_by": "date,domain"},
    timeout=20,
)
report = response.json()
if response.status_code != 200:
    raise RuntimeError(report["error"]["message"])

for row in report["data"]:
    print(row["date"], row["domain"], row["revenue"])

// Node.js 18 or later
const params = new URLSearchParams({ from: "2026-09-30", to: "2026-10-06", group_by: "date,domain" });

const response = await fetch(`https://visionforgex.com/api/v1/reports/?${params}`, {
  headers: { Authorization: `Bearer ${process.env.VFX_API_KEY}` },
});
const report = await response.json();
if (!response.ok) throw new Error(report.error.message);

for (const row of report.data) {
  console.log(row.date, row.domain, row.revenue);
}

{
    "data": [
        {
            "date": "2026-09-30",
            "domain": "example.com",
            "impressions": 48210,
            "clicks": 395,
            "revenue": 86.7312,
            "ecpm": 1.8,
            "ctr": 0.82
        },
        {
            "date": "2026-09-30",
            "domain": "example.org",
            "impressions": 9120,
            "clicks": 61,
            "revenue": 11.4004,
            "ecpm": 1.25,
            "ctr": 0.67
        }
    ],
    "totals": {
        "impressions": 57330,
        "clicks": 456,
        "revenue": 98.1316,
        "ecpm": 1.71,
        "ctr": 0.8
    },
    "meta": {
        "from": "2026-09-30",
        "to": "2026-09-30",
        "group_by": ["date", "domain"],
        "filters": { "domain": [], "ad_format": [] },
        "currency": "USD",
        "rows": 2,
        "complete": true,
        "pending_conversion_rows": 0,
        "data_updated_at": "2026-10-06T21:40:12Z"
    }
}

Rows come back in order: by date, then domain, then format. A combination with no impressions has no row, so fill gaps with zero on your side.

With format=csv the same rows come back as a file, with the unit in each column name:

date,domain,impressions,clicks,revenue_usd,ecpm_usd,ctr_percent
2026-09-30,example.com,48210,395,86.7312,1.80,0.82
2026-09-30,example.org,9120,61,11.4004,1.25,0.67

Sites

GEThttps://visionforgex.com/api/v1/sites/

The domains your key can report on. Use it to check a domain's spelling before you filter by it.

{
    "data": [
        { "domain": "example.com", "status": "live" },
        { "domain": "example.org", "status": "waiting_for_approval" }
    ],
    "meta": { "count": 2 }
}

status is live for a site that is approved and serving, and waiting_for_approval for one our team has not reviewed yet.

Account

GEThttps://visionforgex.com/api/v1/

Which account the key belongs to, how many sites it covers, the limits, and when the figures were last refreshed. The answer is the one shown under Keys and your first call. It is the right call for a health check.

Errors

An error has an HTTP status and a body in one shape. Branch on code; message is written for a person and can change. Quote request_id when you write to us. It is also in the X-Request-Id header of every answer.

{
    "error": {
        "code": "range_too_long",
        "message": "One request covers at most 90 days. Ask for a longer period in several requests.",
        "request_id": "9b1f04c2a7d35e68"
    }
}

Limits and good habits

• 60 requests a minute and 5,000 a day for an account. The day starts at 00:00 UTC.
• Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time).
• 90 days in one request. For a longer history, ask month by month.
• The figures change a few times a day, not every minute. Once an hour is as often as it is worth asking.
• Keep the key out of your code repository. Read it from an environment variable or a secrets store, as the examples do.

A daily job that keeps a copy of your figures up to date is one line:

# Once a day, a little after midnight UTC: yesterday is new, and the two days before it may have been corrected.
curl "https://visionforgex.com/api/v1/reports/?days=4&group_by=date,domain,ad_format&format=csv" \
  -H "Authorization: Bearer $VFX_API_KEY" \
  -o visionforgex-latest.csv

The address has v1 in it. We add fields and options to v1 without notice, so ignore fields you do not know. Anything that would break a working integration goes into a new version, and v1 keeps running beside it.