Ads

An ad is the creative and its landing page. It takes its price, surfaces and geo targets from its ad set.

On the ai and ugc surfaces, Adzen uses your copy as written. On static, Adzen writes the call to action for each publisher page, using your cta as the starting point.

Which creative fields a placement shows depends on the placement’s ad format. body, price and the image appear only on formats that have a slot for them.

The ad object

{
  "id": "ad_2864",
  "object": "ad",
  "ad_set_id": "adset_8271",
  "external_id": "cr-99812",
  "name": "Water heaters, same day",
  "status": "active",
  "review_status": "approved",
  "effective_status": "active",
  "serving_issues": [],
  "creative": {
    "brand_name": "Acme Home Services",
    "title": "Same-day water heater repair",
    "body": "Licensed Dallas plumbers. Upfront pricing.",
    "cta": "Book a plumber",
    "price": "From $89",
    "target_url": "https://acme.example/water-heaters",
    "file_id": "file_5120"
  },
  "created_time": 1791590400,
  "updated_time": 1791590400
}

Creative text

A failed rule is a 400 invalid_value with param set to the field, like creative.title.

Create an ad

POST /ads

Ads are created paused and go to Adzen review. An ad serves when its effective_status is active. See Serving status.

curl -X POST https://api.adzen.ai/v1/ad-manager/ads \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8d1c-cr-99812' \
  -d '{
    "ad_set_id": "adset_8271",
    "external_id": "cr-99812",
    "creative": {
      "brand_name": "Acme Home Services",
      "title": "Same-day water heater repair",
      "body": "Licensed Dallas plumbers. Upfront pricing.",
      "cta": "Book a plumber",
      "price": "From $89",
      "target_url": "https://acme.example/water-heaters",
      "file_id": "file_5120"
    }
  }'

The response is 200 with the new ad object, status paused and review_status in_review.

Retrieve, list and update

On GET /ads, status must be active, paused or archived, and review_status must be in_review, approved or rejected. A malformed ad_set_id or campaign_id, like abc, returns an empty list. GET /ads/{id} and POST /ads/{id} return 200 with the ad object.

An update with an empty body, {}, changes nothing and returns the ad as it is. Changes to name and external_id apply right away, with no review.

Editing a live ad

Any update that includes creative sends the ad to in_review, even when the values are the same as before. The creative fields you send are merged over the current ones.

If Adzen rejects an ad that has no edit in review, the ad stops serving until you send an edit and Adzen approves it.

Status changes, and changes to the ad set’s price or the campaign’s flight dates and budgets, apply right away with no review.

Concurrent changes

One change to an ad runs at a time. An edit or status change that arrives while another is running on the same ad is a 409 ad_busy. Retry with backoff for up to 30 seconds.

Change status

Each returns 200 with the ad object.

• Archive is final. activate or pause on an archived ad is a 409 archived. archive on an archived ad returns 200.
• activate on an ad in an archived ad account is a 409 ad_account_archived.

Images

POST /files

Upload an image and use it on any ad in the same ad account.

The body is multipart/form-data with exactly these fields:

curl -X POST https://api.adzen.ai/v1/ad-manager/files \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F ad_account_id=acct_61 \
  -F purpose=ad_image \
  -F file=@water-heater.jpg

The response is 200 with the file object. Use its id as creative.file_id; ads reference images only by id.

{
  "id": "file_5120",
  "object": "file",
  "ad_account_id": "acct_61",
  "purpose": "ad_image",
  "content_type": "image/jpeg",
  "width": 1200,
  "height": 1200,
  "bytes": 482113,
  "created_time": 1791590400
}

A file part with no Content-Type, or application/octet-stream, is accepted when its bytes are a PNG or JPEG.

GET /files and GET /files/{id}

List the images in your ad accounts, or retrieve one, for example to recover an id after a timed-out upload. GET /files is a list, newest first by default; filter with ad_account_id. Its updated_after filter compares against created_time. Each item, and the response of GET /files/{id}, is a file object.

Error responses

Errors use the Ads API error body. Authentication errors, the non-US 403, 429 rate_limit_exceeded and 503 temporarily_unavailable apply to every endpoint and are listed in Errors.