Saltar al contenido principal
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 '
{
  "name": "<string>",
  "bids": [
    {
      "target": {
        "id": "<string>",
        "type": "product"
      },
      "amount": "<unknown>",
      "location": "Santiago",
      "trigger": {
        "type": "<string>",
        "value": {
          "words": [
            "<string>"
          ],
          "matchType": "exact"
        }
      },
      "triggers": [],
      "formatProperties": {
        "bannerAssets": [
          {
            "dimensions": {
              "width": 123,
              "height": 123
            },
            "url": "<string>",
            "contentType": "image/png",
            "size": 123,
            "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
            "content": {},
            "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          }
        ],
        "slotId": "<string>",
        "adFormat": "<string>",
        "deviceType": "desktop"
      }
    }
  ],
  "campaignType": "manual",
  "isActive": true,
  "externalCampaignId": "<string>",
  "isAutoTrigger": false,
  "startDate": "2023-11-07T05:31:56Z",
  "endDate": "2023-11-07T05:31:56Z",
  "targetRoas": 10.25,
  "promotionType": {
    "bannerAssets": [
      {
        "dimensions": {
          "width": 123,
          "height": 123
        },
        "url": "<string>",
        "contentType": "image/png",
        "size": 123,
        "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
        "content": {},
        "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ],
    "slotId": "<string>",
    "adFormat": "<string>",
    "deviceType": "desktop"
  },
  "status": "approved",
  "adFormat": "listing",
  "budget": {
    "amount": 123,
    "type": "daily"
  },
  "chargeType": "CPM",
  "productIds": [
    "<string>"
  ],
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "<string>",
        "segmentId": 123,
        "multiplier": 2
      }
    ]
  },
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "<string>",
        "segmentId": 123
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "<string>",
        "segmentId": 123
      }
    ]
  },
  "autobiddingObjective": "impressions",
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "marketplaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "startDate": "2023-11-07T05:31:56Z",
  "endDate": "2023-11-07T05:31:56Z",
  "isActive": true,
  "isSmart": true,
  "campaignType": "manual",
  "status": "approved",
  "createdAt": "2023-11-07T05:31:56Z",
  "chargeType": "CPM",
  "externalVendorId": "<string>",
  "adFormat": "listing",
  "isAutoTrigger": true,
  "vendorId": "<string>",
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "bidCount": 123,
  "budget": {
    "amount": 123,
    "amountRemaining": 123,
    "amountCarryover": 123,
    "amountUsed": 123,
    "type": "daily"
  },
  "statusUpdatedBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "campaignBehaviorData": "<string>",
  "campaignBehaviorDataByDay": "<string>",
  "exclusivityPrice": 123,
  "targetRoas": 123,
  "externalCampaignId": "<string>",
  "autobiddingObjective": "impressions",
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "<string>",
        "segmentId": 123,
        "multiplier": 2
      }
    ]
  },
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "<string>",
        "segmentId": 123
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "<string>",
        "segmentId": 123
      }
    ]
  },
  "promotionType": {
    "bannerAssets": [
      {
        "dimensions": {
          "width": 123,
          "height": 123
        },
        "url": "<string>",
        "contentType": "image/png",
        "size": 123,
        "assetId": "asset_01j713j64yfsvtj4bs3ccpy5ca",
        "content": {},
        "jsonTemplateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ],
    "slotId": "<string>",
    "adFormat": "<string>",
    "deviceType": "desktop"
  }
}

Autorizaciones

​
Authorization
string
header
requerido

A valid API key generated in Topsort's UI.

Parámetros de consulta

​
vendor_id
string
requerido

The ID of the vendor.

Minimum string length: 1

Cuerpo

application/json

The request body of campaign creation.

​
name
string
requerido

The name of the campaign.

Minimum string length: 1
Ejemplo:

"Bola-Bola Ad campaign"

​
bids
BidCreate · object[]
requerido

An array of bids for this campaign.

Minimum array length: 1
​
campaignType
enum<string>
requerido

The bidding method for the campaign. Note: The value 'exclusive' is deprecated for this endpoint. Use exclusive campaign endpoints instead.

Opciones disponibles:
manual,
autobidding,
exclusive
​
isActive
boolean
predeterminado:true

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

​
externalCampaignId
string | null

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

​
isAutoTrigger
boolean
predeterminado:false

Whether the campaign is auto-triggered.

​
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.

​
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.

​
targetRoas
number | null

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

Rango requerido: 0.5 <= x <= 20
​
promotionType
BannerAd · object
obsoleto

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

​
status
enum<string>
predeterminado:approved

For a banner campaign, its initial review status.

Opciones disponibles:
approved,
pending,
rejected
​
adFormat
enum<string> | null

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

Opciones disponibles:
listing,
banner
Ejemplo:

"listing"

​
budget
BudgetCreate · object

The assigned budget for the campaign.

​
chargeType
enum<string> | null

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.

Opciones disponibles:
CPM,
CPC,
CPA
​
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 array length: 200
​
multiplierConfig
CampaignMultiplierConfig · object

The multipliers of the campaign.

​
targetingFilters
CampaignTargetingFilters · object

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

​
exclusionFilters
CampaignExclusionFilters · object

The segments that the campaign will not target.

​
autobiddingObjective
enum<string> | null

The objective of the campaign, only for autobidding campaigns.

Opciones disponibles:
impressions,
clicks,
conversions,
revenue
​
walletId
string<uuid> | null

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

Respuesta

Successful Response

The campaign model.

​
campaignId
string<uuid>
requerido

The ID of the campaign.

​
marketplaceId
string<uuid>
requerido

The ID of the marketplace.

​
name
string
requerido

The name of the campaign.

Minimum string length: 1
Ejemplo:

"Bola-Bola Ad campaign"

​
startDate
string<date-time>
requerido

The starting date of the campaign.

​
endDate
string<date-time>
requerido

The end date of the campaign.

​
isActive
boolean
requerido

Whether this campaign is active.

​
isSmart
boolean
requerido

Whether this campaign is "smart".

​
campaignType
enum<string>
requerido

The bidding method for the campaign.

Opciones disponibles:
manual,
autobidding,
exclusive
​
status
enum<string>
requerido

Represents the review status of a banner campaign.

Opciones disponibles:
approved,
pending,
rejected
​
createdAt
string<date-time>
requerido

When was this campaign created.

​
chargeType
requerido

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.

Opciones disponibles:
CPM,
CPC,
CPA
​
externalVendorId
string
requerido
obsoleto

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

Minimum string length: 1
​
adFormat
enum<string>
requerido

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

Opciones disponibles:
listing,
banner,
sponsored_brand,
exclusive_listing,
exclusive_banner,
travel_listing,
flight_listing
Ejemplo:

"listing"

​
isAutoTrigger
boolean
requerido

Whether the campaign is auto-triggered.

​
vendorId
string
requerido

The ID of the vendor.

Minimum string length: 1
​
walletId
string<uuid>
requerido

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

​
bidCount
integer
requerido

The amount of active bids associated with this campaign.

​
budget
Budget · object

The budget assigned to the campaign.

​
statusUpdatedBy
string<uuid> | null

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.

​
campaignBehaviorData
string | null
obsoleto

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

​
campaignBehaviorDataByDay
string | null
obsoleto

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

​
exclusivityPrice
integer | null

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

​
targetRoas
number | null

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

​
externalCampaignId
string | null

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

​
autobiddingObjective
enum<string> | null

The autobidding objective for the campaign.

Opciones disponibles:
impressions,
clicks,
conversions,
revenue
​
multiplierConfig
CampaignMultiplierConfig · object

The multiplier configuration for the campaign.

​
targetingFilters
CampaignTargetingFilters · object

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

​
exclusionFilters
CampaignExclusionFilters · object

The segments that the campaign will not target.

​
promotionType
BannerAd · object
obsoleto

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