Skip to main content
POST
/
advertisers
Create advertiser
curl --request POST \
  --url https://api.interchange.io/api/v2/buyer/advertisers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Corp",
  "brand": "nike.com"
}
'
{
  "id": "12345",
  "name": "Acme Corp",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-20T14:45:00Z",
  "sandbox": true,
  "campaignBudgetType": "total_budget",
  "primaryCurrency": "USD",
  "description": "Global advertising account for Acme Corporation",
  "linkedBrand": {
    "id": "brand_123",
    "name": "Acme Brand",
    "domain": "acme.com",
    "manifest": {
      "name": "Acme Corporation",
      "url": "https://www.acme.com",
      "logos": [
        {
          "url": "<string>",
          "tags": [
            "<string>"
          ],
          "width": 123,
          "height": 123
        }
      ],
      "colors": {
        "primary": "#FF5733",
        "secondary": "<string>",
        "accent": "<string>",
        "background": "<string>",
        "text": "<string>"
      },
      "fonts": {
        "primary": "Roboto",
        "secondary": "<string>",
        "fontUrls": [
          "<string>"
        ]
      },
      "tone": "Professional, friendly, and innovative",
      "tagline": "Innovation for Everyone",
      "assets": [
        {
          "assetId": "<string>",
          "assetType": "<string>",
          "url": "<string>",
          "name": "<string>",
          "description": "<string>",
          "tags": [
            "<string>"
          ],
          "width": 123,
          "height": 123,
          "durationSeconds": 1,
          "fileSizeBytes": 123,
          "format": "<string>",
          "metadata": {}
        }
      ],
      "productCatalog": {
        "feedUrl": "<string>",
        "categories": [
          "<string>"
        ],
        "lastUpdated": "2023-11-07T05:31:56Z"
      },
      "disclaimers": [
        {
          "text": "<string>",
          "required": true,
          "context": "<string>"
        }
      ],
      "industry": "Technology",
      "targetAudience": "Small business owners aged 25-45",
      "contact": {
        "email": "jsmith@example.com",
        "phone": "<string>",
        "website": "<string>"
      },
      "metadata": {
        "createdDate": "2023-11-07T05:31:56Z",
        "updatedDate": "2023-11-07T05:31:56Z",
        "version": "1.0.0"
      }
    },
    "logoUrl": "https://acme.com/logo.png",
    "industry": "Technology",
    "colors": {
      "primary": "#FF5733"
    },
    "tagline": "Innovation for Everyone",
    "tone": "Professional, friendly, and innovative"
  },
  "brand": "nike.com",
  "brandWarning": "<string>",
  "linkedAccounts": [
    {
      "linkId": "<string>",
      "accountId": "<string>",
      "name": "<string>",
      "sources": [
        {
          "storefrontId": 0,
          "storefrontName": "<string>",
          "sourceId": "<string>",
          "sourceName": "<string>"
        }
      ],
      "status": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "credentialId": "42"
    }
  ],
  "utmConfig": [
    {
      "paramKey": "utm_campaign",
      "paramValue": "{CAMPAIGN_ID}"
    }
  ],
  "dataDelivery": {
    "credentials": [
      {
        "credentialId": "<string>",
        "name": "<string>",
        "config": {
          "type": "GCS",
          "bucket": "<string>"
        },
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "statusError": "<string>",
        "validatedAt": "<string>",
        "expiresAt": "<string>"
      }
    ],
    "outputs": [
      {
        "outputConfigId": "<string>",
        "enabled": true,
        "credentialId": "<string>",
        "credentialName": "<string>",
        "deliveryConfig": {
          "type": "GCS",
          "pathPrefix": "",
          "format": "JSONL"
        },
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "syncWeeklyDay": 3
      }
    ]
  },
  "frequencyCaps": [
    {
      "max_impressions": 3,
      "window": {
        "interval": 2,
        "unit": "seconds"
      },
      "id": "12345",
      "targetId": "camp_abc123",
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "archivedAt": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json

Request body for creating a new advertiser

​
name
string
required

Name of the advertiser

Required string length: 1 - 255
Example:

"Acme Corp"

​
brand
string
required

Brand domain (e.g., "nike.com") or brand website URL. Brand identity is resolved from /.well-known/brand.json, the AdCP registry, or Brandfetch enrichment.

Minimum string length: 1
Example:

"nike.com"

​
description
string

Optional description of the advertiser

Maximum string length: 1000
Example:

"Global advertising account for Acme Corporation"

​
saveBrand
boolean
default:false

When true, auto-saves the resolved brand identity to the AdCP registry if the brand is not yet registered. Normally not required for advertiser creation when enrichment succeeds; set this only after reviewing enrichment or when the user confirms registry persistence is desired.

​
linkedAccounts
object[]

Accounts to link to this advertiser at creation time. Each entry references a discovered account from a partner.

​
optimizationApplyMode
enum<string>

Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. Defaults to "MANUAL".

Available options:
AUTO,
MANUAL
​
campaignBudgetType
enum<string>

How budget is allocated by campaign. "total_budget" means the campaign budget covers both media spend and fees. Defaults to "total_budget".

Available options:
total_budget
​
primaryCurrency
string

Primary ISO 4217 currency for this advertiser. Defaults to USD. Campaigns and media-buy products under this advertiser must use this currency.

Required string length: 3
Pattern: ^[A-Za-z]{3}$
Example:

"USD"

​
sandbox
boolean
default:false

When true, this advertiser operates in sandbox mode. All ADCP operations will use sandbox-flagged accounts — no real platform calls, no real spend. Cannot be changed after creation.

​
utmConfig
object[]

Default UTM (Urchin Tracking Module) parameters for this advertiser. These are appended to landing page URLs during clickthrough redirection. Campaign-level UTM config can override these per param key.

Maximum array length: 20
​
dataDelivery
object

Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API.

​
frequencyCaps
object[]

Buyer-side frequency cap configs to apply to this advertiser. Enforced by Scope3 across all publishers; distinct from publisher-side caps in package target_overlay.

Response

Create advertiser

Advertiser resource representation

​
id
string
required

Unique identifier for the advertiser

Example:

"12345"

​
name
string
required

Name of the advertiser

Example:

"Acme Corp"

​
status
enum<string>
required

Current status of the advertiser

Available options:
ACTIVE,
ARCHIVED
​
createdAt
string<date-time>
required

When the advertiser was created (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Example:

"2025-01-15T10:30:00Z"

​
updatedAt
string<date-time>
required

When the advertiser was last updated (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Example:

"2025-01-20T14:45:00Z"

​
sandbox
boolean
required

When true, this advertiser is in sandbox mode. All ADCP operations use sandbox-flagged accounts. Cannot be changed after creation.

​
optimizationApplyMode
enum<string>
required

Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval.

Available options:
AUTO,
MANUAL
​
campaignBudgetType
enum<string>
required

How budget is allocated by campaign. "total_budget" means the campaign budget covers both media spend and fees.

Available options:
total_budget
​
primaryCurrency
string
required

Primary ISO 4217 currency for this advertiser. New campaign budgets default to this currency. Selected product pricing must match the campaign budget currency.

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"USD"

​
description
string

Description of the advertiser

Example:

"Global advertising account for Acme Corporation"

​
linkedBrand
object

The brand linked to this advertiser. Only present when includeBrand=true is passed to the list endpoint.

​
brand
string

The brand domain associated with this advertiser

Example:

"nike.com"

​
brandWarning
string

Warning about brand resolution (e.g., manifest not found)

​
linkedAccounts
object[]

Linked partner accounts for this advertiser. Only present when includeAccounts=true is passed to the list endpoint.

​
utmConfig
object[]

Seat-level UTM parameter configuration. Only present when UTM params are configured for this advertiser.

​
dataDelivery
object

Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API.

​
frequencyCaps
object[]

Buyer-side frequency cap configs for this advertiser. Always present on single-GET; on LIST only when includeFrequencyCaps=true.