Skip to main content
POST
/
campaigns
Create campaign
curl --request POST \
  --url https://api.agentic.scope3.com/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"
  }
}
'
{
  "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",
    "brief": "<string>",
    "flightDates": {
      "startDate": "2025-01-15T00:00:00Z",
      "endDate": "2025-03-31T23:59:59Z"
    },
    "budget": {
      "total": 1,
      "currency": "USD",
      "dailyCap": 1,
      "pacing": "EVEN"
    },
    "constraints": {
      "channels": [
        "<string>"
      ],
      "countries": [
        "<string>"
      ]
    },
    "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"
      }
    ],
    "mediaBuys": [
      {
        "mediaBuyId": "<string>",
        "name": "<string>",
        "status": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "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
            }
          }
        ]
      }
    ]
  }
}

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

​
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

​
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

​
utmConfig
object

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

Response

Create campaign

Response containing a single campaign

​
campaign
object
required

Campaign resource representation