Skip to main content
POST
/
public
/
v1
/
campaign-service
/
campaigns
Create Campaign
curl --request POST \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "adFormat": "listing",
  "autobiddingObjective": "impressions",
  "bids": [
    {
      "amount": 1,
      "formatProperties": {
        "adFormat": "banner",
        "bannerAssets": [
          {
            "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
            "content": {},
            "contentType": "image/png",
            "dimensions": {
              "height": 1080,
              "width": 1920
            },
            "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "size": 123,
            "url": "<string>"
          }
        ],
        "deviceType": "desktop",
        "slotId": "<string>"
      },
      "location": "Santiago",
      "target": {
        "id": "p_8983",
        "type": "product"
      },
      "trigger": {
        "type": "keyword",
        "value": {
          "matchType": "exact",
          "words": [
            "<string>"
          ]
        }
      },
      "triggers": []
    }
  ],
  "budget": {
    "amount": 1000,
    "type": "daily"
  },
  "campaignType": "manual",
  "chargeType": "CPM",
  "endDate": "2023-11-07T05:31:56Z",
  "externalCampaignId": "<string>",
  "isActive": true,
  "isAutoTrigger": false,
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "multiplier": 2,
        "segmentId": 1,
        "type": "user_segment"
      }
    ]
  },
  "name": "Bola-Bola Ad campaign",
  "productIds": [
    "<string>"
  ],
  "promotionType": {
    "adFormat": "banner",
    "bannerAssets": [
      {
        "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
        "content": {},
        "contentType": "image/png",
        "dimensions": {
          "height": 1080,
          "width": 1920
        },
        "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "size": 123,
        "url": "<string>"
      }
    ],
    "deviceType": "desktop",
    "slotId": "<string>"
  },
  "startDate": "2023-11-07T05:31:56Z",
  "status": "approved",
  "targetRoas": 10.25,
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "segmentId": 1,
        "type": "user_segment"
      }
    ]
  },
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}'
{
  "adFormat": "listing",
  "autobiddingObjective": "impressions",
  "bidCount": 123,
  "budget": {
    "amount": 1000,
    "amountCarryover": 123,
    "amountRemaining": 123,
    "amountUsed": 123,
    "type": "daily"
  },
  "campaignBehaviorData": "<string>",
  "campaignBehaviorDataByDay": "<string>",
  "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "campaignType": "manual",
  "chargeType": "CPM",
  "createdAt": "2023-11-07T05:31:56Z",
  "endDate": "2023-11-07T05:31:56Z",
  "exclusivityPrice": 123,
  "externalCampaignId": "<string>",
  "externalVendorId": "<string>",
  "isActive": true,
  "isAutoTrigger": true,
  "isSmart": true,
  "marketplaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "multiplier": 2,
        "segmentId": 1,
        "type": "user_segment"
      }
    ]
  },
  "name": "Bola-Bola Ad campaign",
  "promotionType": {
    "adFormat": "banner",
    "bannerAssets": [
      {
        "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
        "content": {},
        "contentType": "image/png",
        "dimensions": {
          "height": 1080,
          "width": 1920
        },
        "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "size": 123,
        "url": "<string>"
      }
    ],
    "deviceType": "desktop",
    "slotId": "<string>"
  },
  "startDate": "2023-11-07T05:31:56Z",
  "status": "approved",
  "statusUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "targetRoas": 123,
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "segmentId": 1,
        "type": "user_segment"
      }
    ]
  },
  "vendorId": "<string>",
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
Authorization
string
header
required

A valid API key generated in Topsort's UI.

Query Parameters

​
vendor_id
string
required

The ID of the vendor.

Minimum length: 1

Body

application/json

The request body of campaign creation.

​
bids
BidCreate · object[]
required

An array of bids for this campaign.

Minimum length: 1
​
campaignType
enum<string>
required

The bidding method for the campaign.

Available options:
manual,
autobidding,
exclusive
​
name
string
required

The name of the campaign.

Minimum length: 1
Example:

"Bola-Bola Ad campaign"

​
adFormat
enum<string>

The ad format of the campaign. Can be listing or banner.

Available options:
listing,
banner
Example:

"listing"

​
autobiddingObjective
enum<string>

The objective of the campaign, only for autobidding campaigns.

Available options:
impressions,
clicks,
conversions,
revenue
​
budget
object

The assigned budget for the campaign.

​
chargeType
enum<string>

How campaigns are going to be charged, by click, by per mille impressions, or by action. ListingAd campaigns are charged per click by default. BannerAd campaigns are charged per mille impressions by default.CPA is only allowed for listing campaigns. For CPA campaigns, the budget type must be total.

Available options:
CPM,
CPC,
CPA
​
endDate
string<date-time>

Date when to stop the campaign, specified in RFC 3339, if not set the campaign will never stop. This date must be greater than the start date and must be in the future. Must include the Timezone definition.

​
externalCampaignId
string

The external ID of the campaign in the marketplace. Must be unique per marketplace and format combination.

​
isActive
boolean
default:true

Whether the campaign should be activated upon creation.The campaign will start when this is set and the start_date has passed.

​
isAutoTrigger
boolean
default:false

Whether the campaign is auto-triggered.

​
multiplierConfig
object

The multipliers of the campaign.

​
productIds
string[]

The product IDs to be used in the banner campaign. This is only allowed for banner campaigns. When provided, the assets will be associated to the given product IDs.

Maximum length: 200
​
promotionType
object
deprecated

Deprecated. Use adFormat field instead and format properties inside bids. The promotion type and attributes. Ad format must set to 'banner' for exclusive campaigns.

  • BannerAd
  • ListingAd
  • ExclusiveBannerAd
  • ExclusiveListingAd
  • SponsoredBrandAd
​
startDate
string<date-time>

Date when to start the campaign, specified in RFC 3339, if not set that campaign will start immediately after the campaign creation. Must include the Timezone definition.If the start date is in the past, it will be set to the current date.

​
status
enum<string>

For a banner campaign, its initial review status.

Available options:
approved,
pending,
rejected
​
targetRoas
number

Indicates the vendor's goal. For banners, use autobiddingObjective instead. ROAS >12 is rare and depends on product metrics and attribution model.

Required range: 0.5 <= x <= 20
​
targetingFilters
object

The segments that the campaign will participate for (and will not for other segments not here).

​
walletId
string<uuid>

The uuid of the wallet to be used with this campaign.

Response

Successful Response

The campaign model.

​
adFormat
enum<string>
required

The ad format of the campaign. Can be listing or banner.

Available options:
listing,
banner,
sponsored_brand,
exclusive_listing,
exclusive_banner,
travel_listing,
flight_listing
​
bidCount
integer
required

The amount of active bids associated with this campaign.

​
campaignId
string<uuid>
required

The ID of the campaign.

​
campaignType
enum<string>
required

The bidding method for the campaign.

Available options:
manual,
autobidding,
exclusive
​
chargeType
required

How campaigns are going to be charged, by click, by per mille impressions, or by action. Campaign charge type.

CPM: cost per mille impressions CPC: cost per click CPA: cost per action. CPA reflects the total cost to achieve a conversion.

Available options:
CPM,
CPC,
CPA
​
createdAt
string<date-time>
required

When was this campaign created.

​
endDate
string<date-time>
required

The end date of the campaign.

​
externalVendorId
string
required
deprecated

The ID of the vendor. Deprecated. Use vendor_id instead.

Minimum length: 1
​
isActive
boolean
required

Whether this campaign is active.

​
isAutoTrigger
boolean
required

Whether the campaign is auto-triggered.

​
isSmart
boolean
required

Whether this campaign is "smart".

​
marketplaceId
string<uuid>
required

The ID of the marketplace.

​
name
string
required

The name of the campaign.

Minimum length: 1
Example:

"Bola-Bola Ad campaign"

​
startDate
string<date-time>
required

The starting date of the campaign.

​
status
enum<string>
required

Represents the review status of a banner campaign.

Available options:
approved,
pending,
rejected
​
vendorId
string
required

The ID of the vendor.

Minimum length: 1
​
walletId
string<uuid>
required

The uuid of the wallet to be used with this campaign.

​
autobiddingObjective
enum<string>

The autobidding objective for the campaign.

Available options:
impressions,
clicks,
conversions,
revenue
​
budget
object

The budget assigned to the campaign.

​
campaignBehaviorData
string
deprecated

Deprecated. This field is always null. For behavioral data use reporting service.

​
campaignBehaviorDataByDay
string
deprecated

Deprecated. This field is always null. For behavioral data use reporting service.

​
exclusivityPrice
integer

Daily price for an exclusive campaign, can only be set if a campaign is exclusive

​
externalCampaignId
string

The external ID of the campaign in the marketplace. Must be unique per marketplace and format combination.

​
multiplierConfig
object

The multiplier configuration for the campaign.

​
promotionType
object
deprecated

Deprecated. Use adFormat field instead and format properties inside bids. The promotion type and attributes. Ad format must set to 'banner' for exclusive campaigns.

  • BannerAd
  • ListingAd
  • ExclusiveBannerAd
  • ExclusiveListingAd
  • SponsoredBrandAd
​
statusUpdatedBy
string<uuid>

The ID of the user who reviewed the campaign. If it's null and the status is not "pending" then it means this campaign has autoapproval status.

​
targetRoas
number

The target return on ad spend (ROAS) for this campaign. This is only applicable for autobidding listing campaigns.

​
targetingFilters
object

The segments that the campaign will participate for (and will not for other segments not here).