> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Campaign > Creates a campaign with its associated budget and bids. Supports all campaign types except exclusive campaigns. ## OpenAPI ````yaml /openapi.json post /public/v1/campaign-service/campaigns openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. paths: /public/v1/campaign-service/campaigns: post: tags: - Campaign API summary: Create Campaign description: |- Creates a campaign with its associated budget and bids. Supports all campaign types except exclusive campaigns. operationId: create_campaign parameters: - name: vendor_id in: query required: true schema: type: string minLength: 1 description: The ID of the vendor. description: The ID of the vendor. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_PublicCampaignCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_PublicCampaign' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_HTTPValidationError' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_PublicCampaignCreateRequest: properties: name: type: string minLength: 1 title: Name description: The name of the campaign. examples: - Bola-Bola Ad campaign isActive: type: boolean title: Isactive description: >- Whether the campaign should be activated upon creation.The campaign will start when this is set _and_ the `start_date` has passed. default: true externalCampaignId: title: Externalcampaignid description: >- The external ID of the campaign in the marketplace. Must be unique per marketplace and format combination. oneOf: - type: string - type: 'null' isAutoTrigger: type: boolean title: Isautotrigger description: Whether the campaign is auto-triggered. default: false startDate: type: string format: date-time title: Startdate description: >- Date when to start the campaign, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), 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: type: string format: date-time title: Enddate description: >- Date when to stop the campaign, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), 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. default: '9999-12-31T22:59:59.999999Z' targetRoas: title: Targetroas description: >- Indicates the vendor's goal. For banners, use autobiddingObjective instead. ROAS >12 is rare and depends on product metrics and attribution model. oneOf: - type: number maximum: 30 minimum: 0.5 - type: 'null' bids: items: $ref: '#/components/schemas/Advanced_APIs_BidCreate' type: array minItems: 1 title: Bids description: An array of bids for this campaign. campaignType: $ref: '#/components/schemas/Advanced_APIs_CampaignType' description: >- The bidding method for the campaign. Note: The value 'exclusive' is deprecated for this endpoint. Use exclusive campaign endpoints instead. status: $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' description: For a banner campaign, its initial review status. default: approved adFormat: title: Adformat description: The ad format of the campaign. Can be listing or banner. examples: - listing oneOf: - type: string enum: - listing - banner - type: 'null' budget: description: The assigned budget for the campaign. oneOf: - $ref: '#/components/schemas/Advanced_APIs_BudgetCreate' - type: 'null' chargeType: description: >- 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. CPA is supported for manual and autobidding campaigns with any budget type. oneOf: - $ref: '#/components/schemas/Advanced_APIs_ChargeType' - type: 'null' productIds: items: type: string type: array maxItems: 250 uniqueItems: true title: Productids description: >- 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. autobiddingObjective: description: The objective of the campaign, only for autobidding campaigns. oneOf: - $ref: '#/components/schemas/Advanced_APIs_AutobiddingObjective' - type: 'null' targetRoasPreference: description: >- Target ROAS preset (aggressive, moderate, conservative). When set, the numeric target ROAS is resolved from marketplace bidcalc configuration. When only target_roas is provided without this field, preference is stored as custom. oneOf: - $ref: '#/components/schemas/Advanced_APIs_TargetRoasPreference' - type: 'null' walletId: title: Walletid description: The uuid of the wallet to be used with this campaign. oneOf: - type: string format: uuid - type: 'null' fallbackWalletId: title: Fallbackwalletid description: The optional fallback wallet to be used with this campaign. oneOf: - type: string format: uuid - type: 'null' type: object required: - name - bids - campaignType title: PublicCampaignCreateRequest description: The request body of campaign creation. Advanced_APIs_PublicCampaign: properties: campaignId: type: string format: uuid title: Campaignid description: The ID of the campaign. marketplaceId: type: string format: uuid title: Marketplaceid description: The ID of the marketplace. name: type: string minLength: 1 title: Name description: The name of the campaign. examples: - Bola-Bola Ad campaign budget: description: The budget assigned to the campaign. oneOf: - $ref: '#/components/schemas/Advanced_APIs_Budget' - type: 'null' startDate: type: string format: date-time title: Startdate description: The starting date of the campaign. endDate: type: string format: date-time title: Enddate description: The end date of the campaign. isActive: type: boolean title: Isactive description: Whether this campaign is active. isSmart: type: boolean title: Issmart description: Whether this campaign is "smart". campaignType: $ref: '#/components/schemas/Advanced_APIs_CampaignType' status: $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' statusUpdatedBy: title: Statusupdatedby description: >- 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. oneOf: - type: string format: uuid - type: 'null' campaignBehaviorData: title: Campaignbehaviordata description: >- Deprecated. This field is always null. For behavioral data use reporting service. deprecated: true oneOf: - type: string - type: 'null' campaignBehaviorDataByDay: title: Campaignbehaviordatabyday description: >- Deprecated. This field is always null. For behavioral data use reporting service. deprecated: true oneOf: - type: string - type: 'null' createdAt: type: string format: date-time title: Createdat description: When was this campaign created. chargeType: title: Chargetype description: >- How campaigns are going to be charged, by click, by per mille impressions, or by action. oneOf: - $ref: '#/components/schemas/Advanced_APIs_ChargeType' - $ref: '#/components/schemas/Advanced_APIs_ExclusiveCampaignChargeType' exclusivityPrice: title: Exclusivityprice description: >- Daily price for an exclusive campaign, can only be set if a campaign is exclusive oneOf: - type: integer - type: 'null' targetRoas: title: Targetroas description: >- The target return on ad spend (ROAS) for this campaign. This is only applicable for autobidding listing campaigns. oneOf: - type: number - type: 'null' externalCampaignId: title: Externalcampaignid description: >- The external ID of the campaign in the marketplace. Must be unique per marketplace and format combination. oneOf: - type: string - type: 'null' externalVendorId: type: string minLength: 1 title: Externalvendorid description: The ID of the vendor. Deprecated. Use vendor_id instead. deprecated: true adFormat: $ref: '#/components/schemas/Advanced_APIs_AdFormat' description: The ad format of the campaign. Can be listing or banner. examples: - listing isAutoTrigger: type: boolean title: Isautotrigger description: Whether the campaign is auto-triggered. autobiddingObjective: description: The autobidding objective for the campaign. oneOf: - $ref: '#/components/schemas/Advanced_APIs_AutobiddingObjective' - type: 'null' vendorId: type: string minLength: 1 title: Vendorid description: The ID of the vendor. walletId: type: string format: uuid title: Walletid description: The uuid of the wallet to be used with this campaign. fallbackWalletId: title: Fallbackwalletid description: The optional fallback wallet to be used with this campaign. oneOf: - type: string format: uuid - type: 'null' bidCount: type: integer title: Bidcount description: >- The amount of active bids associated with this campaign. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true type: object required: - campaignId - marketplaceId - name - startDate - endDate - isActive - isSmart - campaignType - status - createdAt - chargeType - externalVendorId - adFormat - isAutoTrigger - vendorId - walletId - bidCount title: PublicCampaign description: The campaign model. Advanced_APIs_HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/Advanced_APIs_ValidationError' type: array title: Detail type: object title: HTTPValidationError Advanced_APIs_BidCreate: properties: amount: format: int32 title: Amount description: >- Maximum amount of money willing to offer for a sponsored slot in minor units of currency according to ISO 4217. oneOf: - type: integer exclusiveMaximum: 2000000000 exclusiveMinimum: 0 - type: 'null' location: title: Location description: >- 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. examples: - Santiago oneOf: - type: string minLength: 1 - type: 'null' target: $ref: '#/components/schemas/Advanced_APIs_Entity' triggers: items: oneOf: - $ref: '#/components/schemas/Advanced_APIs_KeywordTrigger-Input' - $ref: '#/components/schemas/Advanced_APIs_CategoryTrigger' - $ref: '#/components/schemas/Advanced_APIs_CategoriesTrigger' - $ref: '#/components/schemas/Advanced_APIs_ProductTrigger' - $ref: '#/components/schemas/Advanced_APIs_NoContextTrigger' - $ref: >- #/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger - $ref: >- #/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger description: When should this bid participate in an auction. discriminator: propertyName: type mapping: categories: $ref: '#/components/schemas/Advanced_APIs_CategoriesTrigger' categories_from_campaign_products: $ref: >- #/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger category: $ref: '#/components/schemas/Advanced_APIs_CategoryTrigger' keyword: $ref: '#/components/schemas/Advanced_APIs_KeywordTrigger-Input' keywords_from_campaign_products: $ref: >- #/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger nocontext: $ref: '#/components/schemas/Advanced_APIs_NoContextTrigger' product: $ref: '#/components/schemas/Advanced_APIs_ProductTrigger' type: array minItems: 1 title: Triggers description: >- A list of objects that trigger the appearance of this bid on an auction. default: [] formatProperties: description: >- The format properties of the bid. This field is required for banner ads. Should be not set for listing ads. oneOf: - $ref: '#/components/schemas/Advanced_APIs_BannerAd-Input' - type: 'null' type: object required: - target title: BidCreate description: The request model for bid creation. Advanced_APIs_CampaignType: type: string enum: - manual - autobidding - exclusive title: CampaignType description: The bidding method for the campaign. Advanced_APIs_CampaignStatus: type: string enum: - approved - pending - rejected title: CampaignStatus description: Represents the review status of a banner campaign. Advanced_APIs_BudgetCreate: properties: amount: type: integer exclusiveMaximum: 50000000000 exclusiveMinimum: 0 format: int64 title: Amount description: >- The amount of money in the budget in minor units of currency according to ISO 4217. examples: - 1000 type: $ref: '#/components/schemas/Advanced_APIs_Type' examples: - daily type: object required: - amount - type title: BudgetCreate description: A budget creation request. Advanced_APIs_ChargeType: type: string enum: - CPM - CPC - CPA title: ChargeType description: >- 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. Advanced_APIs_AutobiddingObjective: type: string enum: - impressions - clicks - conversions - revenue title: AutobiddingObjective Advanced_APIs_TargetRoasPreference: type: string enum: - aggressive - conservative - moderate - custom title: TargetRoasPreference Advanced_APIs_Budget: properties: amount: type: integer exclusiveMaximum: 50000000000 exclusiveMinimum: 0 format: int64 title: Amount description: >- The amount of money in the budget in minor units of currency according to ISO 4217. examples: - 1000 amountRemaining: type: integer format: int64 title: Amountremaining description: >- The remaining amount of the budget. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true amountCarryover: type: integer format: int64 title: Amountcarryover description: >- The amount carried over from the last period. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true amountUsed: type: integer format: int64 title: Amountused description: >- The used amount of the budget. This field is deprecated and will be set to 0 once the notice period is over. deprecated: true type: $ref: '#/components/schemas/Advanced_APIs_Type' examples: - daily type: object required: - amount - amountRemaining - amountCarryover - amountUsed - type title: Budget description: A campaign budget. Advanced_APIs_ExclusiveCampaignChargeType: type: string enum: - DAILY title: ExclusiveCampaignChargeType description: Charge types for exclusive campaigns. Advanced_APIs_AdFormat: type: string enum: - listing - banner - sponsored_brand - exclusive_listing - exclusive_banner - travel_listing - flight_listing title: AdFormat description: The type of the auction. Advanced_APIs_ValidationError: properties: loc: items: oneOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError Advanced_APIs_Entity: properties: id: type: string maxLength: 256 minLength: 1 title: Id description: The unique ID of the entity. examples: - p_8983 type: $ref: '#/components/schemas/Advanced_APIs_CampaignEntityType' examples: - product type: object required: - id - type title: Entity description: >- Represents a promotable entity that will be returned upon a winning auction. Advanced_APIs_KeywordTrigger-Input: properties: type: type: string const: keyword title: Type value: $ref: '#/components/schemas/Advanced_APIs_KeywordValue' type: object required: - type - value title: KeywordTrigger description: |- Collection of keywords that match to a product. Ideal for search results pages. Advanced_APIs_CategoryTrigger: properties: type: type: string const: category title: Type value: $ref: '#/components/schemas/Advanced_APIs_CategoryValue' type: object required: - type - value title: CategoryTrigger description: |- Catalog-based category from a product. Ideal for category product listing pages. Advanced_APIs_CategoriesTrigger: properties: type: type: string const: categories title: Type value: $ref: '#/components/schemas/Advanced_APIs_CategoriesValue' type: object required: - type - value title: CategoriesTrigger description: |- Catalog-based categories from a product. Ideal for category product listing pages. Not allowed for banner ads. Advanced_APIs_ProductTrigger: properties: type: type: string const: product title: Type value: $ref: '#/components/schemas/Advanced_APIs_ProductValue' type: object required: - type - value title: ProductTrigger description: The ID of a product. Advanced_APIs_NoContextTrigger: properties: type: type: string const: nocontext title: Type type: object required: - type title: NoContextTrigger description: |- A blank trigger for times when none of the other filters are used. Ideal for Landing pages. Advanced_APIs_KeywordsFromCampaignProductsTrigger: properties: type: type: string const: keywords_from_campaign_products title: Type type: object required: - type title: KeywordsFromCampaignProductsTrigger description: Keywords from campaign products. Advanced_APIs_CategoriesFromCampaignProductsTrigger: properties: type: type: string const: categories_from_campaign_products title: Type type: object required: - type title: CategoriesFromCampaignProductsTrigger description: Categories from campaign products. Advanced_APIs_BannerAd-Input: properties: bannerAssets: items: $ref: '#/components/schemas/Advanced_APIs_BannerAsset' type: array minItems: 1 title: Bannerassets description: The assets for the banner campaign, if `adFormat` is `banner`. slotId: type: string minLength: 1 pattern: ^[\w!\"#$%&'()*+,\-._/:;<>?@\[\]^\{\}~=\\]*$ title: Slotid description: The external slot id provided by the marketplace. deviceType: $ref: '#/components/schemas/Advanced_APIs_DeviceType' description: The targeted device for this campaign, if `adFormat` is `banner`. default: desktop examples: - desktop adFormat: type: string const: banner title: Adformat type: object required: - bannerAssets - slotId - adFormat title: BannerAd Advanced_APIs_Type: type: string enum: - daily - weekly - monthly - total title: Type description: The periodicity of the budget. Advanced_APIs_CampaignEntityType: type: string enum: - product - brand - vendor - url title: CampaignEntityType description: The type of the entity to be advertised. Advanced_APIs_KeywordValue: properties: words: items: type: string type: array maxItems: 5000 title: Words description: The list of keywords. matchType: $ref: '#/components/schemas/Advanced_APIs_KeywordMatchType' type: object required: - words - matchType title: KeywordValue Advanced_APIs_CategoryValue: properties: categoryId: type: string title: Categoryid description: The ID of the category. type: object required: - categoryId title: CategoryValue Advanced_APIs_CategoriesValue: properties: fromProduct: type: string title: Fromproduct description: The ID of the product to retrieve categories from. type: object required: - fromProduct title: CategoriesValue Advanced_APIs_ProductValue: properties: productId: type: string title: Productid description: The ID of the product. type: object required: - productId title: ProductValue Advanced_APIs_BannerAsset: properties: url: title: Url description: >- The url where the asset is located. If asset_id is provided, this field will be ignored. oneOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' contentType: title: Contenttype description: >- The mime type of the asset. If asset_id is provided, this field will be ignored. examples: - image/png oneOf: - type: string minLength: 1 - type: 'null' dimensions: $ref: '#/components/schemas/Advanced_APIs_Dimensions' size: title: Size description: >- The file size of the asset, in bytes. If asset_id is provided, this field will be ignored. oneOf: - type: integer - type: 'null' assetId: title: Assetid description: Asset id, if created using the asset API. examples: - asset_01j713j64yfsvtj4bs3ccpy5ca oneOf: - type: string maxLength: 33 - type: 'null' content: title: Content description: >- Custom additional metadata about the banner. If provided, the asset_id and url fields will be ignored. Maximum size is 20KB when serialized. oneOf: - additionalProperties: oneOf: - type: string - items: type: string type: array type: object - type: 'null' jsonTemplateId: title: Jsontemplateid description: >- The id of the json template that was used to create the json content. oneOf: - type: string format: uuid - type: 'null' type: object required: - dimensions title: BannerAsset description: >- Represents the banner resource file, it's location, mimetype, dimensions and size. Advanced_APIs_DeviceType: type: string enum: - mobile - desktop title: DeviceType description: The device where a banner ad should appear. Advanced_APIs_KeywordMatchType: type: string enum: - exact - phrase title: KeywordMatchType Advanced_APIs_Dimensions: properties: width: type: integer exclusiveMinimum: 0 title: Width description: The width of the image. examples: - 1920 height: type: integer exclusiveMinimum: 0 title: Height description: The height of the image. examples: - 1080 type: object required: - width - height title: Dimensions description: The width and height of an asset. securitySchemes: Advanced_APIs_HTTPBearer: type: http description: >- 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. scheme: bearer ````