Organization and ad accounts

Each advertiser gets its own ad account, spend cap, statement and API keys.

Organization

`GET /organization`

Returns the organization your key belongs to. The organization key and advertiser keys can both call it.


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


{
  "id": "org_12",
  "object": "organization",
  "name": "Example DSP",
  "status": "active",
  "currency": "USD",
  "time_zone": "America/New_York"
}

Every field is read-only.

Field	Type	Value
`id`	string	`org_` and a number
`object`	string	`organization`
`name`	string	Your organization’s name
`status`	string	`active` or `inactive`
`currency`	string	`USD`
`time_zone`	string	Your organization’s IANA time zone, for example `America/New_York`. `UTC` if none was set. Insights, statements and invoices use it. A new campaign takes it for its daily budget: see Budgets.

The ad account object


{
  "id": "acct_61",
  "object": "ad_account",
  "external_id": "adv-3021",
  "name": "Acme Home Services",
  "domain": "acme.example",
  "status": "active",
  "review_status": "approved",
  "rejection_reasons": [],
  "currency": "USD",
  "spend_limit": { "monthly_spend_limit_micros": 20000000000 },
  "created_time": 1791590400,
  "updated_time": 1791590400
}

Field	Type	Rules
`name`	string	Required on create. Trimmed, 3 to 256 characters, no control characters.
`domain`	string	Required on create. The advertiser’s website host name, like `acme.example`. Lowercased. Up to 253 characters, at least two labels. Each label is 1 to 63 of `a-z`, `0-9` and `-`, and does not start or end with `-`. The last label is not all digits. No scheme, path, port or trailing dot. Use punycode for a non-ASCII name.
`external_id`	string	Optional. Your id for the advertiser. 1 to 256 characters, not blank, no control characters. Unique within your organization. `null` clears it.
`spend_limit`	object	Optional. `{ "monthly_spend_limit_micros": <integer> }` caps the account’s spend per calendar month. The value is 1 to 1,000,000,000,000,000 (`$1B`) and a multiple of `10000` (whole cents). Send `"spend_limit": null`, or `"monthly_spend_limit_micros": null`, to remove the cap. With no cap the object returns `"spend_limit": null`.
`status`	string	Read-only: `active`, `paused` or `archived`. Change it with the status endpoints.
`review_status`	string	Read-only: `pending`, `approved` or `rejected`. Adzen’s review of the account.
`rejection_reasons`	string[]	Read-only. Always present on an ad account. `[]` unless `review_status` is `rejected`; then 1 to 10 reasons, each up to 200 characters. (An ad leaves the field out instead when it is not rejected.)
`currency`	string	Read-only. `USD`.
`created_time`, `updated_time`	integer	Read-only. Unix seconds.

status is what you set. review_status is Adzen’s decision. An ad account serves only while status is active and review_status is approved.

Create an ad account

`POST /ad_accounts`

Only the organization key can create ad accounts. A new account has status: active and review_status: pending. You can create and activate campaigns, ad sets and ads in it while it is in review. Nothing in it serves until Adzen approves the account.

You can create campaigns in a new account as soon as the create call returns. Use the create response as the account’s first state: a GET or list can take a few seconds to include a new account.

Header	Required	Value
`Authorization`	Yes	`Bearer YOUR_ORGANIZATION_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/ad_accounts \
  -H 'Authorization: Bearer YOUR_ORGANIZATION_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f0b1f0e-acct-3021' \
  -d '{
    "name": "Acme Home Services",
    "domain": "acme.example",
    "external_id": "adv-3021",
    "spend_limit": { "monthly_spend_limit_micros": 20000000000 }
  }'

The response is 200 with the ad account object.

Retrieve, list and update

Method	Path	Notes
`GET`	`/ad_accounts`	The accounts your key reaches. List parameters, plus `external_id`.
`GET`	`/ad_accounts/{id}`
`POST`	`/ad_accounts/{id}`	Update `name`, `domain`, `external_id` or `spend_limit`. Returns `200` with the ad account. A `name` or `domain` change sends the account back to review.

Review

Adzen reviews every new ad account. review_status and rejection_reasons show the outcome.

A change to name or domain sends an approved or rejected account back to pending and clears rejection_reasons. The account stops serving until Adzen approves it again.
A change to external_id or spend_limit does not affect review.
To have a rejected account reviewed again, change its name or domain.

Change status

Method	Path	Effect
`POST`	`/ad_accounts/{id}/pause`	Stops serving every ad in the account. Campaign, ad set and ad statuses do not change; each reports a `paused` serving issue with `source.object` `ad_account`.
`POST`	`/ad_accounts/{id}/activate`	Lifts the account pause. Everything that served before serves again.
`POST`	`/ad_accounts/{id}/archive`	Stops serving every ad in the account permanently.

Each call returns 200 with the ad account object. Repeating the current status returns 200. Archive is final: updating, pausing or activating an archived account is 409 archived, and creating or changing anything in it is 409 ad_account_archived.

Which key can do what

Action	Organization key	Advertiser key
`GET /organization`	Yes	Yes
Create ad accounts	Yes	No: `403` `organization_key_required`
Read, update, pause, activate and archive an ad account	Every account in the organization	Its own account
Campaigns, ad sets, ads, files, conversions and insights	Every account in the organization	Its own account
Create, list and revoke API keys	Yes	No: `403` `organization_key_required`

Advertiser API keys

An advertiser key reaches one ad account. You create, list and revoke advertiser keys with the organization key. Each ad account can have up to 20 active keys. A new key works on its first request, as soon as the create call returns. A revoked key stops working within 30 seconds of the revoke.

Method	Path	Effect
`POST`	`/ad_accounts/{id}/api_keys`	Creates a key. The secret is returned only in this response.
`GET`	`/ad_accounts/{id}/api_keys`	Lists the account’s active and revoked keys in the list envelope. Takes `limit`, `after`, `before` and `order`. Secrets are never returned.
`POST`	`/ad_accounts/{id}/api_keys/{key_id}/revoke`	Revokes a key and returns it with `status: revoked`. Revoking a revoked key returns `200` with the same object.

Create a key

The body takes one field:

Field	Type	Required	Rules
`name`	string	Yes	A label for your reference. Trimmed, 1 to 256 characters, no control characters.

Any other field is 400 invalid_value.


curl -X POST https://api.adzen.ai/v1/ad-manager/ad_accounts/acct_61/api_keys \
  -H 'Authorization: Bearer YOUR_ORGANIZATION_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2b7e-acct_61-key-1' \
  -d '{ "name": "Acme production" }'


{
  "id": "key_93",
  "object": "api_key",
  "ad_account_id": "acct_61",
  "name": "Acme production",
  "secret": "adz_sk_live_7Rk2...x7Qp",
  "last_four": "x7Qp",
  "status": "active",
  "created_time": 1791590400,
  "last_used_time": null
}

Field	Type	Rules
`id`	string	`key_` and a number
`ad_account_id`	string	The ad account the key reaches
`name`	string	Your label
`secret`	string	Only in the create response. Store it then. `adz_sk_live_` followed by 43 characters; treat it as an opaque string.
`last_four`	string	Read-only. The last four characters of the secret.
`status`	string	Read-only: `active` or `revoked`.
`created_time`	integer	Read-only. Unix seconds.
`last_used_time`	integer	Read-only. Unix seconds when the key last made a request, accurate to about one minute. `null` if it has made none.

A retry of a create with the same Idempotency-Key returns 409 secret_shown_once and no secret. List the account’s keys to find the key. If you lost the secret, revoke the key and create a new one.

To rotate an advertiser key, create a new key, switch to it, then revoke the old one.

Budgets and billing

Delivery stops at whichever limit is reached first:

Level	Control	Headroom returns
Campaign	`budget.daily_spend_limit_micros`	At the campaign’s midnight. See Budgets.
Campaign	`budget.lifetime_spend_limit_micros`	When you raise or remove it
Ad account	`spend_limit.monthly_spend_limit_micros`	At the start of the calendar month in your organization’s time zone, or when you raise or remove it
Organization	Your credit limit with Adzen	When Adzen records a payment against your invoices, or raises the limit

Each limit that stops delivery shows as a serving issue.

Each ad account gets a monthly statement, and your organization gets one invoice that covers them all. Both use your organization’s time zone. A statement’s total is the ad account’s spend_micros for that month in Insights, rounded half up to the cent.

Error responses

These are the codes specific to ad accounts and keys. Every code is in the error catalog.

Status	`code`	When	Retry?
`400`	`invalid_value`	A field failed validation, or the body has a field the endpoint does not take. `param` names it.	No
`403`	`organization_key_required`	An advertiser key tried to create an ad account or use an `/api_keys` route.	No
`404`	`not_found`	No such ad account or key in your organization	No
`409`	`external_id_conflict`	Another ad account in your organization already uses this `external_id`	No
`409`	`archived`	The ad account is archived and cannot change	No
`409`	`ad_account_archived`	You created or changed something in an archived ad account	No
`409`	`managed_by_adzen`	Adzen manages this object; it can be read but not changed.	No
`409`	`organization_inactive`	Your organization is not active	No
`409`	`ad_account_inactive`	The ad account is not active and cannot get new keys	No
`409`	`key_limit_reached`	The ad account already has 20 active keys	No. Revoke a key first.
`409`	`secret_shown_once`	A retry of a key create that already succeeded	No
`503`	`upstream_unavailable`	A temporary error. Send the same request again.	Yes, with backoff