Ad Serving API

Overview

The Ad Serving API gives you full control over ad requests and responses. Use it when serving ads in email, integrating with custom UI flows, or when you need direct access to ad data.

For custom ad styling on websites, the Monetization Framework Custom Template is often simpler.

Quick Example

curl -G https://srv.buysellads.com/ads/CVADC53U.json \
  -d useragent=Mozilla%2F5.0... \
  -d forwardedip=198.51.100.123

The zone key CVADC53U is safe for testing.

Endpoint

Base URL: https://srv.buysellads.com/ads/{zonekey}.json

Required parameters

Parameter	Type	Description
`useragent`	`string`	URL-encoded browser useragent of the client viewing the ad
`forwardedip`	`string`	IPv4 address of the client viewing the ad (not your server's IP)

Optional parameters

Parameter	Type	Description
`ignore`	`string`	Set to `yes` for test mode (loads ads without counting impressions)
`callback`	`string`	Function name for JSONP response
`embedassets`	`string`	Set to `yes` to get base64 images instead of URLs

Response

The API returns an ads array. When an ad is available, the first object contains a statlink (click URL) and creative data:

{
  "ads": [
    {
      "statlink": "//srv.buysellads.com/ads/click/x/...",
      "statimp": "//srv.buysellads.com/ads/imp/x/...",
      "description": "Squarespace is the all-in-one solution for anyone looking to create a beautiful website.",
      "company": "Squarespace",
      "callToAction": "Start a Free Trial",
      "image": "https://cdn4.buysellads.net/uu/1/45011/1558712365-squarespace_icon.png",
      "logo": "https://cdn4.buysellads.net/uu/1/45011/1558712369-squarespace_logo.png",
      "backgroundColor": "#000000",
      "textColor": "#fafafa",
      "pixel": "https://example.com/pixel?t=[timestamp]"
    },
    {}
  ]
}

When no ad is available, statlink is missing:

{
  "ads": [
    {
      "statimp": "//srv.buysellads.com/ads/imp/x/...",
      "zonekey": "CVADC53U"
    },
    {}
  ]
}

Always check for statlink before rendering. If missing, show your fallback content.

See Default Properties for the full list of available fields.

Handling Pixels

Some campaigns include a pixel property for attribution tracking. When present, render it as invisible images:

function renderPixels(pixelString, timestamp) {
  if (!pixelString) return ''

  return pixelString
    .split('||')
    .map(
      (url) =>
        `<img src="${url.replace(
          '[timestamp]',
          timestamp
        )}" style="display:none" />`
    )
    .join('')
}

Multiple pixels are separated by ||. Always replace [timestamp] with the current time.

Concepts

A zone represents a unit of ad inventory (e.g., "Top Sidebar", "In-content"). Each zone has a unique zone key like CVADC53U.

Zones can be grouped into placements for targeting. Most implementations need just one zone per ad location.

Verifying Your Integration

Use browser DevTools to confirm your integration is working correctly.

Check the request

Open DevTools → Network tab
Filter by srv.buysellads.com
Click the request and check Query String Parameters:

Parameter	What to verify
`forwardedip`	Shows the client's IPv4 address (e.g., `198.51.100.123`), not your server's IP
`useragent`	URL-encoded browser useragent string

Check the response

statlink exists → Ad available
statlink missing → No fill, show fallback

Common issues

Server IP instead of client IP — Pass the client IP from X-Forwarded-For header.

Useragent not encoded — URL-encode the useragent string.

No ads returning — Verify your zone key. Use CVADC53U for testing.

Pixels not firing — Check for pixel property and render it.