Campaigns

A campaign sets the flight dates, budgets and landing URL parameters.

The campaign object


{
  "id": "cmpn_412",
  "object": "campaign",
  "ad_account_id": "acct_61",
  "external_id": "io-55120",
  "name": "Acme Home Services Q4",
  "status": "active",
  "effective_status": "active",
  "serving_issues": [],
  "start_time": 1793595600,
  "end_time": 1798779599,
  "budget": {
    "daily_spend_limit_micros": 1500000000,
    "lifetime_spend_limit_micros": 90000000000
  },
  "attribution_window_days": 30,
  "landing_page_configuration": {
    "query_string_template": "utm_source=adzen&dsp_campaign={campaign_external_id}&dsp_ad={ad_external_id}"
  },
  "created_time": 1791590400,
  "updated_time": 1791590400
}

Field	Type	Rules
`ad_account_id`	string	Required on create: `acct_61` or `61`. Cannot change: sending it on update is `400` `invalid_value`.
`name`	string	Required on create. Trimmed, 3 to 256 characters, no control characters.
`external_id`	string	Optional. 1 to 256 characters, not blank, no control characters. Unique within the ad account. `null` clears it.
`start_time`	integer	Optional. Unix seconds, 1 to 32503680000 (the year 3000). If it is unset when you activate the campaign, it is set to that moment.
`end_time`	integer	Optional. Unix seconds, 1 to 32503680000. Must be after `start_time`, on create and on update. At `end_time` the campaign stops everywhere and its `status` becomes `completed`.
`budget.daily_spend_limit_micros`	integer	Optional. Greater than 0, a multiple of `10000` (whole cents), at most `99999999990000` (under `$100M`). Resets at the campaign’s midnight. See Budgets.
`budget.lifetime_spend_limit_micros`	integer	Optional. A positive integer. The total the campaign can spend over its whole flight.
`attribution_window_days`	integer	Optional. `7`, `14` or `30` days from the click; default `30`. See Conversions.
`landing_page_configuration.query_string_template`	string	Optional. Your parameters on every landing URL. Up to 2,048 bytes and 20 parameters. An empty string is `400` `invalid_value`. Send `null` to remove the template. For the format and macros, see Landing URL parameters.
`status`	string	Read-only: `active`, `paused`, `completed` or `archived`. `completed` means `end_time` has passed.
`effective_status`, `serving_issues`	string, object[]	Read-only. See Serving status.
`created_time`, `updated_time`	integer	Read-only. Unix seconds.

Budgets

A budget that is not set reads as null.
On update, a limit you leave out keeps its value. A limit set to null is cleared. "budget": null clears both limits.
Without a daily or lifetime budget, the campaign spends up to the ad account and organization limits.
A campaign’s day starts at midnight in the organization time_zone it was created with. If your organization’s time_zone changes, campaigns created before the change keep the earlier zone.

Create a campaign

`POST /campaigns`

Campaigns are created paused. Activate the campaign when its ad sets and ads are ready. You can create and activate campaigns while the ad account’s review_status is pending; they serve once the account is approved.

Header	Required	Value
`Authorization`	Yes	`Bearer YOUR_API_KEY` (organization key or the ad account’s advertiser key)
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	1 to 255 visible characters. See Idempotency.


curl -X POST https://api.adzen.ai/v1/ad-manager/campaigns \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 0c9a-io-55120' \
  -d '{
    "ad_account_id": "acct_61",
    "external_id": "io-55120",
    "name": "Acme Home Services Q4",
    "start_time": 1793595600,
    "end_time": 1798779599,
    "budget": {
      "daily_spend_limit_micros": 1500000000,
      "lifetime_spend_limit_micros": 90000000000
    }
  }'

The response is 200 with the campaign object.

Retrieve, list and update

Method	Path	Notes
`GET`	`/campaigns`	List parameters, plus the filters below
`GET`	`/campaigns/{id}`
`POST`	`/campaigns/{id}`	Update any writable field except `ad_account_id`. Returns `200` with the campaign.

Filter	Rules
`ad_account_id`	Campaigns in this ad account. An ad account your key does not reach returns an empty list.
`external_id`	Exact match on your own id
`status`	`active`, `paused`, `completed` or `archived`. Any other value is `400`.

Change status

Method	Path	Effect
`POST`	`/campaigns/{id}/activate`	Sets `status` to `active`
`POST`	`/campaigns/{id}/pause`	Stops serving. See How fast a pause takes effect.
`POST`	`/campaigns/{id}/archive`	Stops serving permanently

Each call returns 200 with the campaign object. Repeating the current status returns 200 and changes nothing.

Activation checks run in this order:

An archived campaign is 409 archived.
A campaign in an archived ad account is 409 ad_account_archived.
A campaign whose end_time has passed is 409 flight_ended.

If the checks pass, status becomes active. Whether its ads serve still depends on the ad account, the flight, the budgets, and the ad sets and ads below it: read effective_status.

To run a completed campaign again, set a later end_time, then activate it.

To stop all of one advertiser’s spend at once, pause its ad account.

Error responses

These are the codes specific to campaigns. Every code is in the error catalog.

Status	`code`	When	Retry?
`400`	`invalid_value`	A field failed validation, for example `end_time` not after `start_time`. `param` names the field.	No
`404`	`not_found`	No such campaign in your organization. On create, `param` is `ad_account_id` when the ad account does not exist or your key does not reach it.	No
`409`	`external_id_conflict`	The `external_id` is already used in this ad account	No
`409`	`archived`	The campaign is archived and cannot change	No
`409`	`ad_account_archived`	The ad account is archived; nothing in it can change	No
`409`	`flight_ended`	You activated a campaign whose `end_time` has passed. Set a later `end_time`, then activate it.	No
`503`	`upstream_unavailable`	The request did not complete.	Yes, with backoff. On a create, resend with the same `Idempotency-Key`.