> ## 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 a sponsored brand campaign. > Create a regular sponsored brand campaign using external vendor and slot identifiers. Only V2 sponsored brand campaigns are supported. ## OpenAPI ````yaml /openapi.json post /public/v1/campaign-service/campaigns/sponsored-brand 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/sponsored-brand: post: tags: - Campaign API summary: Create a sponsored brand campaign. description: >- Create a regular sponsored brand campaign using external vendor and slot identifiers. Only V2 sponsored brand campaigns are supported. operationId: public_create_sponsored_brand_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_PublicSponsoredBrandCampaignCreateRequest responses: '201': description: Successful Response content: application/json: schema: $ref: >- #/components/schemas/Advanced_APIs_PublicSponsoredBrandCampaignWithBudget '400': description: Invalid wallet or JSON template content. '404': description: Vendor, wallet, or slot not found. '409': description: Campaign or bid already exists. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_HTTPValidationError' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_PublicSponsoredBrandCampaignCreateRequest: 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. default: true status: $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' description: The initial review status of the sponsored brand campaign. default: approved externalCampaignId: title: Externalcampaignid description: The external ID of the campaign in the marketplace. oneOf: - type: string - type: 'null' isAutoTrigger: type: boolean title: Isautotrigger description: Whether the campaign is auto-triggered. default: false slotId: type: string minLength: 1 title: Slotid description: >- The external slot ID where the sponsored brand campaign will be shown. slotIds: title: Slotids description: >- Additional external slot IDs. If present, each ID replicates the whole bid set. oneOf: - items: type: string type: array maxItems: 10 - type: 'null' schedule: items: $ref: '#/components/schemas/Advanced_APIs_Schedule' type: array maxItems: 1 minItems: 1 title: Schedule description: The schedule for the campaign. content: additionalProperties: true type: object title: Content description: Dynamic content validated against the slot's JSON template. walletId: title: Walletid description: The uuid of the wallet used with this campaign. oneOf: - type: string format: uuid - type: 'null' bids: items: $ref: '#/components/schemas/Advanced_APIs_PublicCreateSponsoredBrandBid' type: array maxItems: 500 minItems: 1 title: Bids description: An array of bids for this campaign. targetRoas: title: Targetroas description: Indicates the vendor's target return on ad spend. oneOf: - type: number maximum: 30 minimum: 0.5 - type: 'null' bidType: $ref: '#/components/schemas/Advanced_APIs_PublicSponsoredBrandBidType' description: The bidding type of the campaign. budget: $ref: '#/components/schemas/Advanced_APIs_BudgetCreate' description: The assigned budget for the campaign. targetRoasPreference: description: Target ROAS preference label. oneOf: - $ref: '#/components/schemas/Advanced_APIs_TargetRoasPreference' - type: 'null' chargeType: $ref: '#/components/schemas/Advanced_APIs_ChargeType' description: How campaigns are charged. default: CPC autobiddingObjective: $ref: '#/components/schemas/Advanced_APIs_AutobiddingObjective' description: The objective of the campaign. default: clicks type: object required: - name - slotId - schedule - content - bids - bidType - budget title: PublicSponsoredBrandCampaignCreateRequest description: Request body for creating a public sponsored brand campaign. Advanced_APIs_PublicSponsoredBrandCampaignWithBudget: 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. vendorId: type: string title: Vendorid description: The external vendor ID. 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 is active. status: $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' description: The approval status of the sponsored brand campaign. externalCampaignId: title: Externalcampaignid description: The external ID of the campaign in the marketplace. oneOf: - type: string - type: 'null' isAutoTrigger: type: boolean title: Isautotrigger description: Whether the campaign is auto-triggered. slotId: type: string title: Slotid description: The external slot ID where the sponsored brand campaign is shown. schedule: items: $ref: '#/components/schemas/Advanced_APIs_Schedule' type: array maxItems: 1 minItems: 1 title: Schedule description: The schedule for the campaign. content: additionalProperties: true type: object title: Content description: Dynamic content validated against the slot's JSON template. walletId: title: Walletid description: The uuid of the wallet used with this campaign. oneOf: - type: string format: uuid - type: 'null' createdAt: type: string format: date-time title: Createdat description: When this campaign was created. updatedAt: type: string format: date-time title: Updatedat description: When this campaign was last updated. targetRoas: title: Targetroas description: Indicates the vendor's target return on ad spend. oneOf: - type: number maximum: 30 minimum: 0.5 - type: 'null' bidType: $ref: '#/components/schemas/Advanced_APIs_PublicSponsoredBrandBidType' description: The bidding type of the campaign. isAgency: type: boolean title: Isagency description: Whether this campaign is promoted by an agency. targetRoasPreference: description: Target ROAS preference label. oneOf: - $ref: '#/components/schemas/Advanced_APIs_TargetRoasPreference' - type: 'null' chargeType: $ref: '#/components/schemas/Advanced_APIs_ChargeType' description: How campaigns are charged. autobiddingObjective: description: The objective of the campaign. oneOf: - $ref: '#/components/schemas/Advanced_APIs_AutobiddingObjective' - type: 'null' budget: $ref: '#/components/schemas/Advanced_APIs_Budget' description: The assigned budget for the campaign. type: object required: - campaignId - marketplaceId - vendorId - name - isActive - status - isAutoTrigger - slotId - schedule - content - createdAt - updatedAt - bidType - isAgency - chargeType - budget title: PublicSponsoredBrandCampaignWithBudget description: A regular sponsored brand campaign returned by the public API. Advanced_APIs_HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/Advanced_APIs_ValidationError' type: array title: Detail type: object title: HTTPValidationError Advanced_APIs_CampaignStatus: type: string enum: - approved - pending - rejected title: CampaignStatus description: Represents the review status of a banner campaign. Advanced_APIs_Schedule: properties: startDate: type: string format: date-time title: Startdate description: The start time of the schedule. endDate: type: string format: date-time title: Enddate description: The end time of the schedule. type: object required: - startDate - endDate title: Schedule description: The schedule for the campaign. Advanced_APIs_PublicCreateSponsoredBrandBid: 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' target: $ref: '#/components/schemas/Advanced_APIs_Entity' triggers: items: oneOf: - $ref: '#/components/schemas/Advanced_APIs_CategoriesTrigger' - $ref: >- #/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger - $ref: '#/components/schemas/Advanced_APIs_CategoryTrigger' - $ref: '#/components/schemas/Advanced_APIs_KeywordTrigger-Input' - $ref: >- #/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger - $ref: '#/components/schemas/Advanced_APIs_ProductTrigger' 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 product: $ref: '#/components/schemas/Advanced_APIs_ProductTrigger' type: array maxItems: 500 minItems: 1 title: Triggers description: >- A list of objects that trigger the appearance of this bid on an auction. formatProperties: $ref: '#/components/schemas/Advanced_APIs_PublicSponsoredBrandAdCreate' description: The public V2 format properties of the bid. location: title: Location description: Optional location associated with this bid. examples: - Santiago oneOf: - type: string minLength: 1 - type: 'null' type: object required: - target - triggers - formatProperties title: PublicCreateSponsoredBrandBid description: A sponsored brand bid creation request for the public API. Advanced_APIs_PublicSponsoredBrandBidType: type: string enum: - manual - autobidding title: PublicSponsoredBrandBidType description: The bidding method for the sponsored brand 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_TargetRoasPreference: type: string enum: - aggressive - conservative - moderate - custom title: TargetRoasPreference 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_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_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_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_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_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_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_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_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_PublicSponsoredBrandAdCreate: properties: imageAssets: items: $ref: '#/components/schemas/Advanced_APIs_PublicSponsoredBrandAsset' type: array maxItems: 500 title: Imageassets description: The image assets for the sponsored brand ad. type: object required: - imageAssets title: PublicSponsoredBrandAdCreate description: The public format properties for sponsored brand bid creation. 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_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_CategoryValue: properties: categoryId: type: string title: Categoryid description: The ID of the category. type: object required: - categoryId title: CategoryValue 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_ProductValue: properties: productId: type: string title: Productid description: The ID of the product. type: object required: - productId title: ProductValue Advanced_APIs_PublicSponsoredBrandAsset: properties: height: type: integer title: Height description: The height of the asset. width: type: integer title: Width description: The width of the asset. contentType: type: string title: Contenttype description: The content type of the asset. contentLength: type: integer exclusiveMinimum: 0 title: Contentlength description: The content length of the asset. url: type: string maxLength: 2083 minLength: 1 format: uri title: Url description: The URL of the asset. type: object required: - height - width - contentType - contentLength - url title: PublicSponsoredBrandAsset Advanced_APIs_KeywordMatchType: type: string enum: - exact - phrase title: KeywordMatchType 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 ````