Serve Endpoint

GET /api/ad/serve — Fetch an ad for a placement.

Parameters

Param	Required	Description
p	Yes	Placement ID (UUID). Identifies which ad slot to fill.
ua	No	User-Agent of the end user. Pass when calling from your server.
ip	No	IPv4 address of the end user. Pass when calling from your server. Without this, all users share one IP and impressions are deduped incorrectly.
country	No	ISO 3166-1 alpha-2 country code (e.g. US, DE). Improves geo targeting when calling server-side.
test	No	Set to 1 to enable test mode. The response will not include an impression_url, so no impression is recorded and no budget is spent.

Response Shape

The response is a JSON object with a single ad key. When an ad is available, it contains:

Field	Type	Description
product_name	string	The advertiser's product name.
headline	string	Ad headline text.
logo	string \| null	URL to the advertiser's logo image.
cta_text	string	Call-to-action label, e.g. "Learn More".
click_url	string	Tracking URL. Use as the href on your CTA link.
impression_url	string \| null	Pixel URL. Load this when the ad is displayed to record the impression. Null in test mode.
colors	object	Brand colors for rendering the ad (see below).
placement_type	string	The placement format, e.g. "banner" or "card".
attribution.texts	string[]	Acceptable attribution labels. Display one near the ad.
attribution.url	string	Link the attribution text to this URL.

Colors Object

The colors object contains hex color values for rendering the ad in the advertiser's brand style:

Key	Default	Description
background	#ffffff	Background color of the ad container.
text	#111111	Color for headline and body text.
cta_background	#111111	Background color of the CTA button.
cta_text	#ffffff	Text color of the CTA button.

No-Fill Response

When no ad is available for a placement (no matching campaign, exhausted budget, inactive placement, etc.), the endpoint returns:

{ "ad": null }

Your integration should handle this gracefully by hiding the ad container or showing fallback content.

Test Mode

Pass test=1 to fetch a real ad without recording an impression. The response will have impression_url set to null, so no budget is consumed. Use this during development and integration testing.

Pending placements automatically return a test ad with placeholder content so you can verify your integration before approval.

Example

Request:

GET /api/ad/serve?p=550e8400-e29b-41d4-a716-446655440000

Response:

{
  "ad": {
    "product_name": "Acme Analytics",
    "headline": "Ship faster with real-time insights",
    "logo": "https://example.com/logo.png",
    "cta_text": "Try Free",
    "click_url": "https://adventory.io/api/ad/click?c=...&p=...",
    "impression_url": "https://adventory.io/api/ad/pixel?t=...&p=...&c=...&cr=...",
    "colors": {
      "background": "#f5f0ff",
      "text": "#1a1a2e",
      "cta_background": "#6c3ce9",
      "cta_text": "#ffffff"
    },
    "placement_type": "banner",
    "attribution": {
      "texts": ["Ad", "Sponsored", "Adventory Ads", "Sponsored by Adventory"],
      "url": "https://adventory.to/ads?utm_source=attribution&utm_medium=ad&utm_content=example.com"
    }
  }
}

Attribution

Every response includes an attribution object. You must display one of the provided texts visibly near the ad, linked to the provided URL.

Field	Type	Description
texts	string[]	An array of acceptable attribution labels. Pick the one that fits your layout best.
url	string	Link the attribution text to this URL. It includes tracking parameters to identify the publisher source.

Attribution Guidelines

The attribution must be:

Visible without scrolling or hovering (not hidden behind a tooltip or modal)
Minimum 9px font size
Readable contrast against its background (at least 3:1 ratio)
Linked to the attribution.url with target="_blank" and rel="noopener"
Placed adjacent to or within the ad container

Acceptable text options, from shortest to longest:

"Ad" — minimal, for tight layouts (e.g., banners)
"Sponsored" — neutral, widely understood
"Adventory Ads" — brand mention, good for cards and larger formats
"Sponsored by Adventory" — full disclosure, recommended when space allows

Removing or hiding the attribution violates our publisher guidelines. We verify attribution during placement review and periodic audits.