Get Campaigns

Endpoint to retrieve campaigns. Campaigns can be filtered by Vendor ID and status.

It is expected to use for getting all campaigns of a marketplace & all campaigns of a vendor in dashboards. Filtering by status is expected to use at review page getting campaigns approved, pending tabs.

GET /public/v1/campaign-service/campaigns

Try it

Get Campaigns

cURL

curl --request GET \
  --url https://api.topsort.com/public/v1/campaign-service/campaigns \
  --header 'Authorization: Bearer <token>'

200

{
  "hasMore": true,
  "campaigns": [
    {
      "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"
      }
    }
  ],
  "next": {
    "offset": 123,
    "limit": 123
  }
}

Authorizations

Authorization · string · header · required

A valid API key generated in Topsort's UI.

Query Parameters

vendor_id · string | null

The ID of the vendor. Omit to get campaigns for all vendors.

Minimum string length: 1

status · enum<string> | null

Filter by the approval status of banner campaigns.

Available options: approved, pending, rejected

offset · integer · default: 0

The pagination offset.

Required range: x >= 0

limit · integer · default: 100

The pagination limit.

Required range: 0 <= x <= 100

is_active · boolean | null

Filter by active/inactive campaigns.

external_campaign_id · string | null

Filter by external campaign ID.

slot_id · string | null

The ID of the slot. Used to filter banner and sponsored brand campaigns by slot.

sort_by_date · enum<string> | null · deprecated

Optional sort by date of campaign creation. Deprecated. Use order_by instead.

Available options: asc, desc

order_by · string | null

Comma-separated order by clauses, e.g. 'created_at:asc,name:desc'. Supported dimensions: created_at, start_date, end_date, name, campaign_id.

Response

200

application/json

Successful Response

The campaigns response.

hasMore · boolean · required

Whether this is the last page of results or not.

campaigns · PublicCampaign · object[] · required

An array of campaigns.

Show child attributes

campaigns. campaignId · string<uuid> · required

The ID of the campaign.

campaigns. marketplaceId · string<uuid> · required

The ID of the marketplace.

campaigns. name · string · required

The name of the campaign.

Minimum string length: 1

campaigns. startDate · string<date-time> · required

The starting date of the campaign.

campaigns. endDate · string<date-time> · required

The end date of the campaign.

campaigns. isActive · boolean · required

Whether this campaign is active.

campaigns. isSmart · boolean · required

Whether this campaign is "smart".

campaigns. campaignType · enum<string> · required

The bidding method for the campaign.

Available options: manual, autobidding, exclusive

campaigns. status · enum<string> · required

Represents the review status of a banner campaign.

Available options: approved, pending, rejected

campaigns. createdAt · string<date-time> · required

When was this campaign created.

campaigns. chargeType · required

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

Available options: CPM, CPC, CPA

campaigns. externalVendorId · string · required · deprecated

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

Minimum string length: 1

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

campaigns. isAutoTrigger · boolean · required

Whether the campaign is auto-triggered.

campaigns. vendorId · string · required

The ID of the vendor.

Minimum string length: 1

campaigns. walletId · string<uuid> · required

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

campaigns. bidCount · integer · required

The amount of active bids associated with this campaign.

campaigns. budget · Budget · object

The budget assigned to the campaign.

Show child attributes

campaigns.budget. amount · integer<int64> · required

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

campaigns.budget. amountRemaining · integer<int64> · required

The remaining amount of the budget.

campaigns.budget. amountCarryover · integer<int64> · required

The amount carried over from the last period.

campaigns.budget. amountUsed · integer<int64> · required

The used amount of the budget.

campaigns.budget. type · enum<string> · required

The periodicity of the budget.

Available options: daily, weekly, monthly, total

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

campaigns. campaignBehaviorData · string | null · deprecated

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

campaigns. campaignBehaviorDataByDay · string | null · deprecated

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

campaigns. exclusivityPrice · integer | null

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

campaigns. targetRoas · number | null

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

campaigns. externalCampaignId · string | null

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

campaigns. autobiddingObjective · enum<string> | null

The autobidding objective for the campaign.

Available options: impressions, clicks, conversions, revenue

campaigns. multiplierConfig · CampaignMultiplierConfig · object

The multiplier configuration for the campaign.

Show child attributes

campaigns.multiplierConfig. isActive · boolean · required

Whether the multiplier is active.

campaigns.multiplierConfig. multipliers · UserSegmentMultiplier · object[] · required

List of multipliers.

Maximum array length: 3

Show child attributes

campaigns.multiplierConfig.multipliers. type · string · required

Multiplier type.

Allowed value: "user_segment"

campaigns.multiplierConfig.multipliers. segmentId · integer · required

Internal user segment ID.

campaigns.multiplierConfig.multipliers. multiplier · number · required

Multiplier value.

Required range: x >= 1

campaigns. targetingFilters · CampaignTargetingFilters · object

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

Show child attributes

campaigns.targetingFilters. isActive · boolean · required

Whether the filter is active.

campaigns.targetingFilters. targetingFilters · TargetingFilter · object[] · required

List of filters.

Maximum array length: 3

Show child attributes

campaigns.targetingFilters.targetingFilters. type · string · required

Segment type.

Allowed value: "user_segment"

campaigns.targetingFilters.targetingFilters. segmentId · integer · required

Internal user segment ID.

campaigns. exclusionFilters · CampaignExclusionFilters · object

The segments that the campaign will not target.

Show child attributes

campaigns.exclusionFilters. isActive · boolean · required

Whether the filter is active.

campaigns.exclusionFilters. exclusionFilters · ExclusionFilter · object[] · required

List of exclusion filters.

Maximum array length: 3

Show child attributes

campaigns.exclusionFilters.exclusionFilters. type · string · required

Segment type.

Allowed value: "user_segment"

campaigns.exclusionFilters.exclusionFilters. segmentId · integer · required

Internal user segment ID.

campaigns. promotionType · BannerAd · 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

Show child attributes

campaigns.promotionType. bannerAssets · BannerAsset · object[] · required

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

Minimum array length: 1

Show child attributes

campaigns.promotionType.bannerAssets. dimensions · Dimensions · object · required

The width and height of an asset.

Show child attributes

campaigns.promotionType.bannerAssets.dimensions. width · integer · required

The width of the image.

campaigns.promotionType.bannerAssets.dimensions. height · integer · required

The height of the image.

campaigns.promotionType.bannerAssets. url · string<uri> | null

The url where the asset is located. If asset_id is provided, this field will be ignored.

Required string length: 1 - 2083

campaigns.promotionType.bannerAssets. contentType · string | null

The mime type of the asset. If asset_id is provided, this field will be ignored.

Minimum string length: 1

Example:

"image/png"

campaigns.promotionType.bannerAssets. size · integer | null

The file size of the asset, in bytes. If asset_id is provided, this field will be ignored.

campaigns.promotionType.bannerAssets. assetId · string | null

Asset id, if created using the asset API.

Maximum string length: 33

Example:

"asset_01j713j64yfsvtj4bs3ccpy5ca"

campaigns.promotionType.bannerAssets. content · Content · object

Custom additional metadata about the banner. If provided, the asset_id and url fields will be ignored. Maximum size is 20KB when serialized.

Show child attributes

campaigns.promotionType.bannerAssets.content. {key}

campaigns.promotionType.bannerAssets. jsonTemplateId · string<uuid> | null

The id of the json template that was used to create the json content.

campaigns.promotionType. slotId · string · required

The external slot id provided by the marketplace.

Minimum string length: 1

campaigns.promotionType. adFormat · string · required

Allowed value: "banner"

campaigns.promotionType. deviceType · enum<string> · default: desktop

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

Available options: mobile, desktop

next · Next · object

The parameters that should be used to fetch the next page.

Show child attributes

next. offset · integer<int32> · required

How many items to skip from the beginning of the list.

next. limit · integer<int32> · required

How many items to return.