Create a sponsored brand campaign.

Create a regular sponsored brand campaign using external vendor and slot identifiers. Only V2 sponsored brand campaigns are supported.

POST /public/v1/campaign-service/campaigns/sponsored-brand

Create a sponsored brand campaign.

cURL

curl --request POST \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns/sponsored-brand \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Bola-Bola Ad campaign",
  "slotId": "<string>",
  "schedule": [
    {
      "startDate": "2023-11-07T05:31:56Z",
      "endDate": "2023-11-07T05:31:56Z"
    }
  ],
  "content": {},
  "bids": [
    {
      "target": {
        "id": "p_8983",
        "type": "product"
      },
      "triggers": [
        {
          "type": "categories",
          "value": {
            "fromProduct": "<string>"
          }
        }
      ],
      "formatProperties": {
        "imageAssets": [
          {
            "height": 123,
            "width": 123,
            "contentType": "<string>",
            "contentLength": 123,
            "url": "<string>"
          }
        ]
      },
      "amount": "<unknown>",
      "location": "Santiago"
    }
  ],
  "budget": {
    "amount": 1000,
    "type": "daily"
  },
  "isActive": true,
  "status": "approved",
  "externalCampaignId": "<string>",
  "isAutoTrigger": false,
  "slotIds": [
    "<string>"
  ],
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "targetRoas": 15.25,
  "chargeType": "CPC",
  "autobiddingObjective": "clicks",
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "user_segment",
        "segmentId": "<string>",
        "multiplier": 0.5
      }
    ]
  },
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  }
}
'

201

{
  "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "marketplaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendorId": "<string>",
  "name": "Bola-Bola Ad campaign",
  "isActive": true,
  "status": "approved",
  "isAutoTrigger": true,
  "slotId": "<string>",
  "schedule": [
    {
      "startDate": "2023-11-07T05:31:56Z",
      "endDate": "2023-11-07T05:31:56Z"
    }
  ],
  "content": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "bidType": "manual",
  "isAgency": true,
  "chargeType": "CPM",
  "budget": {
    "amount": 1000,
    "amountRemaining": 123,
    "amountCarryover": 123,
    "amountUsed": 123,
    "type": "daily"
  },
  "externalCampaignId": "<string>",
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "targetRoas": 15.25,
  "targetRoasPreference": "aggressive",
  "autobiddingObjective": "impressions",
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "user_segment",
        "segmentId": "<string>",
        "multiplier": 0.5
      }
    ]
  },
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  }
}

Authorizations

Authorization · string · header · required

A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key.

Query Parameters

vendor_id · string · required

The ID of the vendor.

Minimum string length: 1

Body

application/json

Request body for creating a public sponsored brand campaign.

name · string · required

The name of the campaign.

Minimum string length: 1

Example:

"Bola-Bola Ad campaign"

slotId · string · required

The external slot ID where the sponsored brand campaign will be shown.

Minimum string length: 1

schedule · Schedule · object[] · required

The schedule for the campaign.

Required array length: 1 element

Show child attributes

content · Content · object · required

Dynamic content validated against the slot's JSON template.

bids · PublicCreateSponsoredBrandBid · object[] · required

An array of bids for this campaign.

Required array length: 1 - 500 elements

Show child attributes

bidType · enum<string> · required

The bidding type of the campaign.

Available options: manual, autobidding

budget · BudgetCreate · object · required

The assigned budget for the campaign.

Show child attributes

isActive · boolean · default: true

Whether the campaign should be activated upon creation.

status · enum<string> · default: approved

The initial review status of the sponsored brand campaign.

Available options: approved, pending, rejected

externalCampaignId · string | null

The external ID of the campaign in the marketplace.

isAutoTrigger · boolean · default: false

Whether the campaign is auto-triggered.

slotIds · string[] | null

Additional external slot IDs. If present, each ID replicates the whole bid set.

Maximum array length: 10

walletId · string<uuid> | null

The uuid of the wallet used with this campaign.

targetRoas · number | null

Indicates the vendor's target return on ad spend.

Required range: 0.5 <= x <= 30

targetRoasPreference · enum<string> | null

Target ROAS preference label.

Available options: aggressive, conservative, moderate, custom

chargeType · enum<string> · default: CPC

How campaigns are charged.

Available options: CPM, CPC, CPA

autobiddingObjective · enum<string> · default: clicks

The objective of the campaign.

Available options: impressions, clicks, conversions, revenue

multiplierConfig · PublicCampaignMultiplierConfig · object | null

The multipliers of the campaign.

Show child attributes

targetingFilters · PublicCampaignTargetingFilters · object | null

The segments that the campaign will participate for.

Show child attributes

exclusionFilters · PublicCampaignExclusionFilters · object | null

The segments that the campaign will not target.

Show child attributes

Response

201

application/json

Successful Response

A regular sponsored brand campaign returned by the public API.

campaignId · string<uuid> · required

The ID of the campaign.

marketplaceId · string<uuid> · required

The ID of the marketplace.

vendorId · string · required

The external vendor ID.

name · string · required

The name of the campaign.

Minimum string length: 1

Example:

"Bola-Bola Ad campaign"

isActive · boolean · required

Whether the campaign is active.

status · enum<string> · required

The approval status of the sponsored brand campaign.

Available options: approved, pending, rejected

isAutoTrigger · boolean · required

Whether the campaign is auto-triggered.

slotId · string · required

The external slot ID where the sponsored brand campaign is shown.

schedule · Schedule · object[] · required

The schedule for the campaign.

Required array length: 1 element

Show child attributes

content · Content · object · required

Dynamic content validated against the slot's JSON template.

createdAt · string<date-time> · required

When this campaign was created.

updatedAt · string<date-time> · required

When this campaign was last updated.

bidType · enum<string> · required

The bidding type of the campaign.

Available options: manual, autobidding

isAgency · boolean · required

Whether this campaign is promoted by an agency.

chargeType · enum<string> · required

How campaigns are charged.

Available options: CPM, CPC, CPA

budget · Budget · object · required

The assigned budget for the campaign.

Show child attributes

externalCampaignId · string | null

The external ID of the campaign in the marketplace.

walletId · string<uuid> | null

The uuid of the wallet used with this campaign.

targetRoas · number | null

Indicates the vendor's target return on ad spend.

Required range: 0.5 <= x <= 30

targetRoasPreference · enum<string> | null

Target ROAS preference label.

Available options: aggressive, conservative, moderate, custom

autobiddingObjective · enum<string> | null

The objective of the campaign.

Available options: impressions, clicks, conversions, revenue

multiplierConfig · PublicCampaignMultiplierConfig · object | null

The multipliers of the campaign.

Show child attributes

targetingFilters · PublicCampaignTargetingFilters · object | null

The segments that the campaign will participate for.

Show child attributes

exclusionFilters · PublicCampaignExclusionFilters · object | null

The segments that the campaign will not target.

Show child attributes