`POST /ugc/process`

Match a contextual ad to a piece of user-generated content.

Request

Endpoint

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

Headers

Header	Required	Value
`X-API-Key`	Yes	Your subscription key
`Content-Type`	Yes	`application/json`
`X-Forwarded-For`	No	Client IP (for geo targeting)

Body

{
  post_id: string      // Your unique identifier for the post
  message: string      // The post text (max 10,000 chars)
  meta?: {
    location?: string  // ISO country/subdivision (e.g. "US-CA"). Optional —
                       // falls back to IP-based geo lookup.
  }
}

Example

curl -X POST https://api.adzen.ai/ugc/process \
  -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",
    "meta": { "location": "US-WA" }
  }'

Response

200 OK

{
  "post_id": "thread-12345",
  "ads": [
    {
      "ad_id": "ad-abc123",
      "title": "Need a plumber? Same-day service in Seattle",
      "cta": "Book Now",
      "click_through_url": "https://api.adzen.ai/click/abc123",
      "advertiser_name": "Seattle Plumbing Co",
      "pricing_model": {
        "type": "cpc",
        "bid_amount": 0.85
      },
      "relevancy_score": 0.92,
      "ttl_seconds": 300,
      "pixel_trackers": [
        {
          "vendor": "adzen",
          "tracker_type": "impression",
          "url": "https://api.adzen.ai/pixel/abc123"
        }
      ]
    }
  ]
}

Response fields

Field	Type	Description
`post_id`	string	Echo of the request `post_id`
`ads`	array	Matched ads, ordered by relevance. Empty array when no ad passes matching gates.
`ads[].ad_id`	string	Unique ad identifier. Pass this on impression and disable calls.
`ads[].title`	string	Short headline for the ad
`ads[].cta`	string	Call-to-action button text
`ads[].click_through_url`	string	URL to open on ad click (slug-based for tracking)
`ads[].advertiser_name`	string	Human-readable advertiser name
`ads[].pricing_model.type`	string	`"cpc"`, `"cpm"`, or `"cpa"`
`ads[].pricing_model.bid_amount`	number	Bid in USD
`ads[].relevancy_score`	number	0-1 score from the matching pipeline
`ads[].ttl_seconds`	integer	Refresh the match after this many seconds
`ads[].pixel_trackers`	array	Third-party pixels to fire when the ad is displayed

Error responses

Status	Meaning
`400`	Validation error (missing `post_id`, empty `message`, message too long)
`401`	Missing or invalid API key
`429`	Rate limit exceeded
`502`	Downstream matching service failure

An empty ads array is not an error. It means the matching pipeline found no ad relevant to the content, or all candidates were filtered by quality gates.

Overview POST /ugc/impression