Update advertiser

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

PUT /api/v2/buyer/advertisers/{advertiserId} Updates an existing advertiser through the raw v2 API. All body fields are optional — send only what you want to change. Brand domain, an already-known country scope, currency, and reporting time zone can change only before the first campaign or seller-account binding. After that, the raw v2 API refuses a brand change; an account administrator changes the brand for future buys through save_advertiser instead. A brand the advertiser has used stays reserved to it, archived included; the exception is an archived sandbox advertiser, which releases every brand it has used. Changing back to an earlier brand reuses its seller accounts where their links still exist; a link that a newer link at the same seller agent replaced may need to be found or provisioned again. Currency and reporting time zone stay fixed. A legacy advertiser whose country scope is still unknown may classify it once even after first use. sandbox is fixed at creation.

In the app

In Apostra, everything about an advertiser lives on the advertiser. Its settings open as one Task titled Advertiser settings. Open it from Settings on an advertiser’s row on the Advertisers Page, from the pencil beside the advertiser in the left rail, or from the Media Partners Page. An agent opens it with open_add_advertiser and the advertiser’s advertiserId. The Task’s header shows the advertiser’s status (active or archived) and a Sandbox label on a sandbox advertiser. The brand domain and currency fields each carry a status chip (for the brand, Resolved, Pending, or Not set), and when the brand or currency is missing, the field’s helper text says what to ask Murph to set. You can change the name, description, channels, and, until the advertiser has a campaign or linked seller account, the reporting time zone. The brand domain, countries, currency, and environment show as read-only, each with a short reason. Until the advertiser has a campaign or linked seller account, the brand domain, countries and currency can still be changed through this endpoint or an agent; after that they are fixed. The environment is fixed when the advertiser is created. In a Media Company account, Advertiser settings is available for your House and Self-serve advertisers. You can change the name and the reporting time zone there. A Scope3-operated System advertiser has no settings action. The Task also shows Client access for these advertisers. Where client access is turned on for your account, you invite someone from the client and decide what they can do; where it is not, the section says so. See Invite and manage a client’s access. Advertiser settings is the only place in the app for an advertiser’s own settings: the account Settings menu no longer has an advertiser section. Save changes saves the advertiser, opens the Advertisers Page, and closes the Task. Cancel closes it without saving. If the Advertisers Page can’t open, the Task stays open with the error and a Done button. Once the Task closes, it doesn’t come back when you reopen that chat. Creating an advertiser works the same way, except the confirmation stays open so you can switch into the new advertiser or add another, until you choose Done. Buyer-owned labels are managed separately through V3 MCP save_advertiser, not this REST endpoint. See Dimensions and labels.

Request

curl

curl -X PUT https://api.apostra.com/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "channels": ["display", "olv", "ctv"],
    "optimizationApplyMode": "AUTO",
    "frequencyCaps": [
      { "max_impressions": 5, "window": { "interval": 7, "unit": "days" } }
    ]
  }'

Parameters

Field	Type	Required	Notes
`advertiserId`	string (path)	Yes	Unique identifier for the advertiser
`name`	string	No	Updated name (1–255 chars)
`description`	string	No	Updated description (max 1000 chars)
`brand`	string	No	Brand domain. Can be re-keyed through this API only before the first campaign or seller-account binding. Afterwards an account administrator changes it for future buys with `save_advertiser`, which previews the effect first
`brandCountries`	array	No	BrandKey country scope. Pass `[]` to confirm that the advertiser works in all countries. An unknown legacy scope may be classified once after first use; changing an already-known scope is locked after the first campaign or seller-account binding
`optimizationApplyMode`	enum	No	`AUTO` or `MANUAL`
`primaryCurrency`	string	No	ISO 4217 currency. Can be re-keyed only before the first campaign or seller-account binding
`preferredTimezone`	string	No	Preferred IANA Reporting time zone. Seller-effective time zones can differ; changeable until the first campaign or seller-account binding
`channels`	array	No	Replaces the editable AdCP channel preferences. Pass `[]` for All channels. Either answer sets `channelsKnown` to `true`. Channel overlap affects automatic seller qualification but does not create advertiser-owned selection edges
`linkedAccounts`	array	No	Accounts to add. Existing links are not removed. Each item may include `credentialId` from list available accounts to disambiguate duplicate account IDs across connected credentials
`utmConfig`	array	No	Replaces all advertiser-level click-URL parameters (max 20). Pass `[]` to clear. Unlike campaign `utmConfig`, there is no additive mode; see How v2 `utmConfig` writes differ by layer
`dataDelivery`	object	No	Data-delivery configuration. Omit to leave existing config untouched
`dataDelivery.credentials`	array	No	Replaces all existing live credentials. Pass `[]` to archive all
`dataDelivery.outputs`	array	No	Replaces all existing advertiser-scoped Data Delivery Outputs. Pass `[]` to clear
`frequencyCaps`	array	No	Replaces all existing non-archived caps. Pass `[]` to clear; omit to leave untouched

Response

{
  "id": "12345",
  "name": "Acme Corporation",
  "description": null,
  "status": "ACTIVE",
  "sandbox": false,
  "optimizationApplyMode": "AUTO",
  "primaryCurrency": "USD",
  "brandCountries": ["DE", "NL"],
  "brandCountriesKnown": true,
  "preferredTimezone": "Europe/Amsterdam",
  "currencyLocked": true,
  "reportingTimezoneLocked": true,
  "channels": ["display", "olv", "ctv"],
  "channelsKnown": true,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-20T14:45:00Z",
  "brand": "acme.com",
  "linkedAccounts": [],
  "utmConfig": [],
  "frequencyCaps": []
}

Returns the full advertiser resource with the applied changes. brandCountriesKnown: true confirms that brandCountries is authoritative. An empty authoritative list is global, not a scope with zero countries. A legacy advertiser may return brandCountriesKnown: false with an empty list; setting brandCountries classifies that scope once, even after first use.

linkedAccounts is additive (existing links stay), but utmConfig and frequencyCaps replace their entire existing set. Pass an empty array to clear, or omit the field to leave it untouched.

If a legacy advertiser has no settings row and its terminal (completed, cancelled, or archived) campaign history spans currencies, include primaryCurrency with the intended currency when you add its brand. The value must match one of the historical campaign currencies. Active campaigns and currently linked seller accounts remain authoritative and still block conflicting currency choices; do not create a duplicate advertiser to bypass that conflict.

Errors

400 VALIDATION_ERROR — invalid field value. The same code, on field brandCountries, means the new brand or countries would create or widen an overlap with another active advertiser of the same brand in your account. The message names that advertiser and suggests countries outside the overlap. An edit that leaves an existing overlap unchanged, or narrows it, is allowed. See One brand, one market.
409 CONFLICT — brand domain, an already-known country scope, currency, or reporting time zone is changed through this API after the first campaign or seller-account binding, or legacy currency evidence cannot be resolved safely. Classifying a still-unknown legacy country scope is the one country-scope exception.
404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated account.

See Errors for the full error contract.

The canonical UI keeps brand, an already-known country scope, and currency out of the edit form. It offers a one-time country classification for a legacy advertiser whose scope is still unknown. Create another advertiser from the UI when known identity values must differ.

Advertiser tasks

All advertiser operations

Advertiser overview

Fields, lifecycle, and concepts

Get advertiser

Read the current state first

Delete advertiser

Archive when done

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Update advertiser

In the app

Request

Parameters

Response

Errors

Advertiser tasks

Advertiser overview

Get advertiser

Delete advertiser

​In the app

​Request

​Parameters

​Response

​Errors

​Related

Advertiser tasks

Advertiser overview

Get advertiser

Delete advertiser

In the app

Request

Parameters

Response

Errors

Related