Ads API

The Ads API creates and runs ad accounts, campaigns, ad sets and ads for the advertisers you represent.

Adzen places the ads in AI answers, on publisher pages and in community feeds, next to content that matches what the advertiser offers.

Object model

Organization   organization key
└── Ad account   one per advertiser, advertiser keys
    └── Campaign   flight dates, budgets
        └── Ad set   price, surfaces
            └── Ad   creative, landing page

Base URL

https://api.adzen.ai/v1/ad-manager

Production accepts requests from US IP addresses. Requests from other addresses get 403.

Authentication

Send your key as a bearer token:

curl https://api.adzen.ai/v1/ad-manager/organization \
  -H 'Authorization: Bearer YOUR_API_KEY'

Use the bearer form. The X-API-Key: YOUR_API_KEY header also works, but a rejected key then gets a different error body (see Errors). If a request carries both, X-API-Key is used.

There are two kinds of key:

For key types and rotation, see Authentication.

Getting started

Build an advertiser in this order. Each step returns the new object with the state shown.

You can run every step while the account and the ad are in review. The ad serves once Adzen approves the ad account and the ad (review_status: approved on both). Each campaign, ad set and ad reports whether it can serve in effective_status, and why not in serving_issues. See Serving status.

Conventions

Request bodies

• Create and update bodies are a JSON object, sent with Content-Type: application/json (or another application/*+json type). A body that is not JSON, is empty, or has no JSON Content-Type is 400 invalid_json. JSON that is not an object is 400 invalid_value with param body.
• A field the endpoint does not take, or a read-only field (id, object, status, effective_status, serving_issues, created_time, updated_time), is 400 invalid_value. param names the field.
• null clears an optional field that has no default. To return attribution_window_days to its default, send 30.
• An update with {} changes nothing and returns the object as it is.
• activate, pause and archive take no body.
• JSON bodies are limited to 2 MiB. A larger body is 413 payload_too_large.
• Validation stops at the first invalid field, and param names it. Geo targets are the exception: every invalid location is listed in one response.
• A successful create returns 200 with the new object.

Status changes

• activate, pause and archive return 200 with the updated object.
• Repeating the current status is a no-op and returns 200.
• Archive is final. Archiving an archived object returns 200. Activating or pausing an archived object is 409 archived.

Lists

Every list endpoint returns the same envelope:

{
  "object": "list",
  "data": [{ "id": "cmpn_412", "object": "campaign" }],
  "first_id": "cmpn_412",
  "last_id": "cmpn_412",
  "has_more": false
}

Every list takes these parameters:

Some lists take more:

Results are ordered by id, not by updated_time. Page with after set to the last_id of the previous page while has_more is true. A query parameter a list does not take is ignored.

Idempotency

Send an Idempotency-Key header on every POST, including POST /files. A retry with the same key and the same request within 24 hours gets the result shown in the table below.

• The key is 1 to 255 visible characters. Anything else is 400 invalid_idempotency_key.
• Only POST requests use it.
• Keys are scoped to your API key.
• “The same request” means the same method, path, If-Match header and body. JSON bodies are compared as JSON, so field order does not matter.
• A request runs to the end even if your connection drops. Retry with the same key to get its response.

The same key with a different request is 409 idempotency_key_reused. A request you correct after a 400 is a different request: send it with a new key.

A POST can get 503 temporarily_unavailable with Retry-After: 5. Nothing ran. Retry with the same key.

Errors

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_value",
    "message": "fixed_cpm_micros must be a multiple of 1000 from 100000 ($0.10) to 1000000000 ($1,000)",
    "param": "fixed_cpm_micros"
  }
}

param is null when no single field is at fault. Branch on type and code. message is text for people; do not parse it.

When the key is sent in X-API-Key, a rejection of the key itself (401, and 403 or 503 from the key check) has the body {"error": "...", "message": "..."} instead. Bearer callers always get the envelope above.

Geo targets have codes of their own. See Geo target errors.

Request IDs

Every response from the API carries a Request-Id header. A rejection of the key itself (401, and 403 or 503 from the key check) and the non-US 403 can come without one. Adzen generates ids as req_ and 32 hex characters. You can send your own Request-Id (or X-Request-Id), 1 to 128 characters of letters, digits, -, _, . or :, and the response echoes it. Quote the id when you contact Adzen about a request.

Rate limits

• An endpoint is the method plus the route template. Pausing two campaigns counts twice against POST /campaigns/{id}/pause.
• Limits count per API key. Each advertiser key has its own.
• Each window is one clock minute and starts at second 0.
• Requests answered 429 and idempotent replays count too.

Over a limit, the API returns 429 rate_limit_exceeded with Retry-After, the seconds until the next minute starts.

The headers on every response to an authenticated request describe the limit with the fewest requests left:

See Rate limits for every product’s limits.

Endpoints