Skip to main content
POST
/
campaigns
Create campaign
curl --request POST \
  --url https://api.interchange.io/api/v2/buyer/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "advertiserId": 12345,
  "name": "Q1 2025 Campaign",
  "flightDates": {
    "startDate": "2025-01-15T00:00:00Z",
    "endDate": "2025-03-31T23:59:59Z"
  },
  "budget": {
    "total": 1,
    "currency": "USD",
    "dailyCap": 1,
    "pacing": "EVEN"
  },
  "campaignType": "DECISIONED"
}
'
{
  "campaign": {
    "campaignId": "cmp_987654321",
    "advertiserId": "12345",
    "name": "Summer 2025 Campaign",
    "status": "DRAFT",
    "optimizationApplyMode": "AUTO",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-20T14:45:00Z",
    "mediaBuyRefs": [
      {
        "mediaBuyId": "mb_ETBn4gJ9Wu",
        "status": "ACTIVE"
      }
    ],
    "campaignType": "DECISIONED",
    "brief": "<string>",
    "flightDates": {
      "startDate": "2025-01-15T00:00:00Z",
      "endDate": "2025-03-31T23:59:59Z"
    },
    "budget": {
      "total": 1,
      "currency": "USD",
      "dailyCap": 1,
      "pacing": "EVEN"
    },
    "mediaBudget": {
      "total": 1,
      "currency": "<string>"
    },
    "fees": [
      {
        "label": "<string>",
        "amount": 1,
        "currency": "<string>",
        "pricingType": "MARGIN",
        "marginPercent": 1,
        "unit": "CPM",
        "unitPrice": 1
      }
    ],
    "allocatedBudget": 7500,
    "unallocatedBudget": 2500,
    "pacingPeriods": {
      "mode": "weight",
      "periods": [
        {
          "label": "<string>",
          "start": "<string>",
          "end": "<string>",
          "weight": 5,
          "budget": 1
        }
      ]
    },
    "constraints": {
      "channels": [
        "<string>"
      ],
      "countries": [
        "<string>"
      ]
    },
    "storefronts": [
      {
        "id": 42,
        "platformId": "acme-media",
        "name": "Acme Media"
      }
    ],
    "performanceConfig": {
      "optimizationGoals": [
        {
          "kind": "event",
          "eventSources": [
            {
              "eventSourceId": "website_pixel",
              "eventType": "page_view",
              "customEventName": "<string>",
              "valueField": "value",
              "valueFactor": 1
            }
          ],
          "target": {
            "kind": "cost_per",
            "value": 25
          },
          "attributionWindow": {
            "postClick": {
              "interval": 7,
              "unit": "days"
            },
            "postView": {
              "interval": 1,
              "unit": "days"
            }
          },
          "priority": 1
        }
      ]
    },
    "catalogId": 42,
    "discoveryId": "session_abc123",
    "productCount": 15,
    "products": [
      {
        "productId": "prod_123"
      }
    ],
    "audiences": [
      {
        "audienceId": "aud_123",
        "name": "Tech Enthusiasts 25-34",
        "status": "READY",
        "type": "TARGET",
        "enabledAt": "2025-03-01T12:00:00Z"
      }
    ],
    "creativeFormats": {
      "required": [
        {
          "agent_url": "<string>",
          "id": "<string>"
        }
      ],
      "covered": [
        {
          "agent_url": "<string>",
          "id": "<string>"
        }
      ],
      "missing": [
        {
          "agent_url": "<string>",
          "id": "<string>"
        }
      ]
    },
    "mediaBuys": [
      {
        "mediaBuyId": "<string>",
        "name": "<string>",
        "status": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "startTime": "2025-04-14T00:00:00Z",
        "endTime": "2025-04-30T23:59:59Z",
        "products": [
          {
            "productId": "<string>",
            "salesAgentName": "<string>",
            "budget": 123,
            "budgetCurrency": "<string>"
          }
        ],
        "packages": [
          {
            "packageId": "<string>",
            "status": "<string>",
            "productIds": [
              "<string>"
            ],
            "budget": 123,
            "budgetCurrency": "<string>",
            "pacing": "<string>",
            "bidPrice": 123,
            "delivery": {
              "impressions": 123,
              "spend": 123,
              "clicks": 123
            }
          }
        ],
        "optimizationGoals": [
          {
            "kind": "metric",
            "metric": "clicks",
            "reach_unit": "individuals",
            "target_frequency": {},
            "view_duration_seconds": 123,
            "target": {
              "kind": "cost_per",
              "value": 123
            },
            "priority": 123
          }
        ]
      }
    ],
    "dataDelivery": {
      "outputs": [
        {
          "outputConfigId": "<string>",
          "dataDeliveryType": "MB_DELIVERY",
          "cadence": "HOURLY",
          "enabled": true,
          "deliveryConfig": {
            "type": "GCS",
            "bucket": "<string>",
            "pathPrefix": "",
            "format": "JSONL"
          },
          "source": "advertiser",
          "createdAt": "<string>",
          "updatedAt": "<string>",
          "syncWeeklyDay": 3
        }
      ]
    },
    "frequencyCaps": [
      {
        "max_impressions": 3,
        "window": {
          "interval": 123,
          "unit": "seconds"
        },
        "id": "12345",
        "targetLevel": "ADVERTISER",
        "targetId": "camp_abc123",
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "archivedAt": "<string>"
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.interchange.io/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json

Request body for creating a campaign

​
advertiserId
integer
required

Advertiser ID that will own this campaign

Required range: x <= 9007199254740991
Example:

12345

​
name
string
required

Name of the campaign

Required string length: 1 - 255
Example:

"Q1 2025 Campaign"

​
flightDates
object
required

Campaign flight dates

​
budget
object
required

Campaign budget configuration

​
campaignType
enum<string>
required

Determines Scope3's role in the campaign. DECISIONED campaigns use Scope3 optimization; ROUTED campaigns pass through to the sales agent using customer credentials. Immutable after creation.

Available options:
DECISIONED,
ROUTED
​
brief
string

Natural language brief for product search context

Maximum string length: 5000
Example:

"Looking for premium video inventory targeting tech enthusiasts"

​
constraints
object

Campaign targeting constraints

​
storefrontIds
integer[]

Storefront IDs the campaign is limited to. When set, every discover_products run for this campaign auto-applies this filter — buyers do not need to resend it. Pass the IDs returned by list_storefronts. Highly encouraged so the campaign only sources inventory from sellers the buyer has chosen.

Maximum array length: 50
Required range: x <= 9007199254740991
Example:
[42, 57]
​
discoveryId
string

Attach an existing discovery session to the campaign

Minimum string length: 1
Example:

"abc123-def456-ghi789"

​
productIds
string[]

Product IDs to pre-select from the discovery session (requires discoveryId)

Example:
["prod_123", "prod_456"]
​
audienceConfig
object

Audience targeting and suppression configuration. On create, listed audiences are attached to the campaign.

​
performanceConfig
object

Performance optimization configuration

​
optimizationApplyMode
enum<string>

Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. If omitted, inherits the advertiser-level setting.

Available options:
AUTO,
MANUAL
​
catalogId
integer

ID of a catalog (from the advertiser catalogs list) to attach to this campaign. Only one catalog may be attached per campaign.

Required range: x <= 9007199254740991
Example:

42

​
pacingPeriods
object

Pacing schedule for the campaign. Defines time-based spend periods with varying intensity. In weight mode, budget is distributed proportionally by weighted days. In budget mode, explicit dollar amounts are set per period. Gaps between periods are treated as pauses (no spend). On execution, each product is split into one package per period with proportional budget.

​
utmConfig
object

UTM (Urchin Tracking Module) parameter configuration for this campaign. Overrides seat-level defaults for matching param keys.

​
dataDelivery
object

Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped delivery for the same dataDeliveryType. Distinct from media-buy reporting fields elsewhere in the API.

​
frequencyCaps
object[]

Buyer-side frequency cap configs to apply to this campaign. Enforced by Scope3 across all publishers.

Response

Create campaign

Response containing a single campaign

​
campaign
object
required

Campaign resource representation