UGC API

POST /v1/ugc/process takes one community post and returns at most one ad to show with it.

POST https://api.adzen.ai/v1/ugc/process

Adzen returns an ad only when its campaign is active, within budget, and allowed on your inventory.

Headers

Body

Adzen ignores body fields it does not recognize.

Example request

curl -X POST https://api.adzen.ai/v1/ugc/process \
  --max-time 30 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "post_id": "thread-12345",
    "message": "Looking for a good plumber in Seattle, our kitchen sink keeps backing up",
    "created_at": "2026-10-29T18:04:12Z",
    "geo_target": { "zipcode": "98103" }
  }'

const response = await fetch('https://api.adzen.ai/v1/ugc/process', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.ADZEN_API_KEY!,
  },
  body: JSON.stringify({
    post_id: 'thread-12345',
    message: 'Looking for a good plumber in Seattle, our kitchen sink keeps backing up',
    created_at: '2026-10-29T18:04:12Z',
    geo_target: { zipcode: '98103' },
  }),
  signal: AbortSignal.timeout(30_000),
})
 
if (!response.ok) throw new Error(`UGC API returned ${response.status}`)
const result = await response.json()
 
if ('no_ad_retry_after_seconds' in result) {
  // No match: do not request this post again until the window passes.
  scheduleRetry(result.no_ad_retry_after_seconds)
} else if (result.ads.length > 0) {
  const ad = result.ads[0]
  const fill = (url: string) =>
    url
      .replaceAll('{SESSION_ID}', encodeURIComponent(sessionId))
      .replaceAll('{EXPERIMENT}', encodeURIComponent(experimentId))
      .replaceAll('{TREATMENT}', encodeURIComponent(treatmentId))
  const clickUrl = fill(ad.click_through_url)
  // Fire each pixel URL when the ad is shown.
  const pixelUrls = ad.pixel_trackers.map((tracker) => fill(tracker.url))
  render(ad, clickUrl, pixelUrls)
}

import os
from urllib.parse import quote
 
import requests
 
response = requests.post(
    'https://api.adzen.ai/v1/ugc/process',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['ADZEN_API_KEY'],
    },
    json={
        'post_id': 'thread-12345',
        'message': 'Looking for a good plumber in Seattle, our kitchen sink keeps backing up',
        'created_at': '2026-10-29T18:04:12Z',
        'geo_target': {'zipcode': '98103'},
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()
 
def fill(url: str) -> str:
    return (
        url.replace('{SESSION_ID}', quote(session_id, safe=''))
        .replace('{EXPERIMENT}', quote(experiment_id, safe=''))
        .replace('{TREATMENT}', quote(treatment_id, safe=''))
    )
 
if 'no_ad_retry_after_seconds' in result:
    schedule_retry(result['no_ad_retry_after_seconds'])
elif result['ads']:
    ad = result['ads'][0]
    click_url = fill(ad['click_through_url'])
    pixel_urls = [fill(t['url']) for t in ad['pixel_trackers']]

Response

A 200 has one of three bodies.

Example: matched ad

{
  "post_id": "thread-12345",
  "ads": [
    {
      "title": "Same-day plumbing repair in Seattle",
      "cta": "Get a free quote from a licensed Seattle plumber.",
      "click_through_url": "https://api.adzen.ai/dea/ugc/redirect/q7m2kx9wd4tp?tid={SESSION_ID}&experiment={EXPERIMENT}&treatment={TREATMENT}",
      "advertiser_name": "Seattle Plumbing Co",
      "pricing_model": { "type": "CPC", "bid_amount": 1.25 },
      "relevancy_score": 0.962,
      "sponsor_logo_url": "https://cdn.example.com/logos/seattle-plumbing.png",
      "ttl_seconds": 28800,
      "eligibility_ttl": 259200,
      "pixel_trackers": [
        {
          "vendor": "adzen",
          "tracker_type": "impression",
          "url": "https://api.adzen.ai/dea/ugc/impression?tid={SESSION_ID}&experiment={EXPERIMENT}&treatment={TREATMENT}&..."
        }
      ]
    }
  ]
}

Response fields

Read ttl_seconds from each response. Do not hard-code it.

Ad unit fields

These fields appear only when your account has ad units configured. Each is present only when the ad unit for this ad declares it. An absent field is left out of the JSON, never sent as null.

When your account has ad units, the unit’s configuration sets which ad text fills title and cta, and their maximum lengths.

Tracking macros

click_through_url and every pixel_trackers[].url contain three macros. Replace each one, wherever it appears, before you render the ad. URL-encode each value.

Rules for the values:

• {SESSION_ID} must be non-empty. A pixel fired with an empty tid (tid=) is not recorded.
• {EXPERIMENT} and {TREATMENT} accept up to 128 characters from A-Z, a-z, 0-9, _, -, ., : and /. Adzen drops a value outside these rules, and the literal values undefined and null.
• An empty {EXPERIMENT} or {TREATMENT}, or one left as its literal text, carries no test data. The impression or click is still recorded.

Treat the rest of each URL as opaque. Do not change or remove its other parameters.

Firing the pixel

Request each pixel_trackers[].url once each time the ad is shown, with GET (for example as an image) or POST. It returns 204 No Content. The click URL returns a 302 redirect to the advertiser’s landing page. Both URLs are on https://api.adzen.ai/dea/. See Tracking URLs and tag traffic.

Adzen counts one impression per {SESSION_ID} value per device (IP address and user agent) in a 5-minute window. A second pixel with the same value from the same device within 5 minutes of the previous one is not counted, even for a different ad. Give each ad view its own value.

No match

When no ad matches the post, the 200 body is a single field:

{ "no_ad_retry_after_seconds": 86400 }

The value follows these rules:

• A first miss returns 86400 (24 hours).
• Each further miss within 24 hours of the previous miss adds 86400: 172800, then 259200, and so on. After 24 hours with no miss, the window starts at 86400 again.
• 600 (10 minutes) means the next request for the post can return an ad.

Honor the value you receive. Do not use a fixed interval.

Repeat requests

Adzen stores one result for each post_id under your key. A repeat request for the same post_id returns the stored ad, and does not match the post again, while the ad stays active, within budget and allowed on your inventory. A changed message under the same post_id keeps the stored ad. A new post_id gets a new match. Retrying a request is safe.

Errors

Retry only 5xx responses and network timeouts. A 200 with empty ads is not an error.

Timing

Set a client timeout of 30 seconds.