Skip to content
Topsort Documentation
API

Create Campaign

POST
/v1/campaign-service/campaigns

Endpoint to create a campaign with its respective budget and bids.

It is expected to use at all types of campaign creations.

Authentication

Topsort’s APIs are authenticated via bearer tokens. Requests must include an authorization header containing your private API key.

Don't have an API key yet? Learn how to generate one.

Authorization
required
string

The header containing a private API key. Format this header as follows:

Authorization: Bearer <YOUR-API-KEY>

Query Parameters

object
vendor_id
required

The ID of the vendor.

string
>= 1 characters

The ID of the vendor.

Request Body

The request body of campaign creation.

application/json
object
adFormat

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

string
Allowed values: listing banner
bids
required

An array of bids for this campaign.

Array<object>
>= 1 items

The request model for bid creation.

object
amount

Maximum amount of money willing to offer for a sponsored slot in minor units of currency according to ISO 4217.

integer format: int64
formatProperties

The format properties of the bid. This field is required for banner ads. Should be not set for listing ads.

object
adFormat
required
string
Allowed values: banner
bannerAssets
required

The assets for the banner campaign, if adFormat is banner.

Array<object>
>= 1 items

Represents the banner resource file, it’s location, mimetype, dimensions and size.

object
contentType
required

The mime type of the asset.

string
>= 1 characters
dimensions
required

The width and height of an asset.

object
height
required

The height of the image.

integer
width
required

The width of the image.

integer
size
required

The file size of the asset, in bytes.

integer
url
required

The url where the asset is located.

string format: uri
>= 1 characters <= 2083 characters
deviceType

The targeted device for this campaign, if adFormat is banner.

string
Allowed values: mobile desktop
slotId
required

The external slot id provided by the marketplace.

string
>= 1 characters /^[\w!\"#$%&'()*+,\-._/:;<>?@\[\]^\{\}~=\\]*$/
location

By using this option you will be able to target this campaign to a specific group.You must define the same location as a parameter on the auction request. Products on a specific campaign will have specific conversion rates, considering the context of location, so it will not interfere with the conversion rates for the same product in other campaigns.

string
>= 1 characters
target
required

Represents a promotable entity that will be returned upon a winning auction.

object
id
required

The unique ID of the entity.

string
>= 1 characters <= 256 characters
type
required
string
Allowed values: product brand vendor url
trigger
One of: discriminator: type

Collection of keywords that match to a product.

Ideal for search results pages.

object
type
required
string
Allowed values: keyword
value
required
object
matchType
required
string
Allowed values: exact
words
required

The list of keywords.

Array<string>
triggers

A list of objects that trigger the appearance of this bid on an auction.

Array
One of: discriminator: type

Collection of keywords that match to a product.

Ideal for search results pages.

object
type
required
string
Allowed values: keyword
value
required
object
matchType
required
string
Allowed values: exact
words
required

The list of keywords.

Array<string>
budget

The assigned budget for the campaign.

object
amount
required

The amount of money in the budget in minor units of currency according to ISO 4217.

integer format: int64
< 2000000000
type
required
string
Allowed values: daily weekly monthly total
campaignType
required

The bidding method for the campaign.

string
Allowed values: manual autobidding exclusive
chargeType

How campaigns are going to be charged, by click or by per mille impressions.ListingAd campaigns are charged per click by default.BannerAd campaigns are charged per mille impressions by default.

string
Allowed values: CPM CPC
endDate

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.

string format: date-time
isActive

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

boolean
default: true
name
required

The name of the campaign.

string
>= 1 characters
promotionType
One of: discriminator: adFormat
object
adFormat
required
string
Allowed values: banner
bannerAssets
required

The assets for the banner campaign, if adFormat is banner.

Array<object>
>= 1 items

Represents the banner resource file, it’s location, mimetype, dimensions and size.

object
contentType
required

The mime type of the asset.

string
>= 1 characters
dimensions
required

The width and height of an asset.

object
height
required

The height of the image.

integer
width
required

The width of the image.

integer
size
required

The file size of the asset, in bytes.

integer
url
required

The url where the asset is located.

string format: uri
>= 1 characters <= 2083 characters
deviceType

The targeted device for this campaign, if adFormat is banner.

string
Allowed values: mobile desktop
slotId
required

The external slot id provided by the marketplace.

string
>= 1 characters /^[\w!\"#$%&'()*+,\-._/:;<>?@\[\]^\{\}~=\\]*$/
startDate

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.

string format: date-time
status

For a banner campaign, its initial review status.

string
Allowed values: approved pending rejected
targetRoas

This is an indication of the vendor’s advertising goals. However, a high ROAS (>12) is generally hard to achieve and depends on the metrics of the advertised products and the purchase attribution model used by the marketplace.

number
>= 0.5 <= 20
walletId

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

string format: uuid

Responses

Successful Response

The campaign model.

application/json
object
adFormat
required

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

string
Allowed values: listing banner
bidCount
required

The amount of active bids associated with this campaign.

integer
budget

The budget assigned to the campaign.

object
amount
required

The amount of money in the budget in minor units of currency according to ISO 4217.

integer format: int64
< 2000000000
amountCarryover
required

The amount carried over from the last period.

integer format: int64
amountRemaining
required

The remaining amount of the budget.

integer format: int64
amountUsed
required

The used amount of the budget.

integer format: int64
type
required
string
Allowed values: daily weekly monthly total
campaignBehaviorData

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

string
campaignBehaviorDataByDay

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

string
campaignId
required

The ID of the campaign.

string format: uuid
campaignType
required

The bidding method for the campaign.

string
Allowed values: manual autobidding exclusive
chargeType
required

How campaigns are going to be charged, by click or by per mille impressions

string
Allowed values: CPM CPC
createdAt
required

When was this campaign created.

string format: date-time
endDate
required

The end date of the campaign.

string format: date-time
exclusivityPrice

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

integer
externalVendorId
required

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

string
>= 1 characters
isActive
required

Whether this campaign is active.

boolean
isSmart
required

Whether this campaign is “smart”.

boolean
isVendorCampaign

Whether this is a promoted shop campaign.

boolean
marketplaceId
required

The ID of the marketplace.

string format: uuid
name
required

The name of the campaign.

string
>= 1 characters
promotionType
One of: discriminator: adFormat
object
adFormat
required
string
Allowed values: banner
bannerAssets
required

The assets for the banner campaign, if adFormat is banner.

Array<object>
>= 1 items

Represents the banner resource file, it’s location, mimetype, dimensions and size.

object
contentType
required

The mime type of the asset.

string
>= 1 characters
dimensions
required

The width and height of an asset.

object
height
required

The height of the image.

integer
width
required

The width of the image.

integer
size
required

The file size of the asset, in bytes.

integer
url
required

The url where the asset is located.

string format: uri
>= 1 characters <= 2083 characters
deviceType

The targeted device for this campaign, if adFormat is banner.

string
Allowed values: mobile desktop
slotId
required

The external slot id provided by the marketplace.

string
>= 1 characters /^[\w!\"#$%&'()*+,\-._/:;<>?@\[\]^\{\}~=\\]*$/
startDate
required

The starting date of the campaign.

string format: date-time
status
required

Represents the review status of a banner campaign.

string
Allowed values: approved pending rejected
statusUpdatedBy

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.

string format: uuid
targetRoas

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

number
vendorId
required

The ID of the vendor.

string
>= 1 characters
walletId
required

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

string format: uuid