> ## 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 Bids > Endpoint to create a bid for a campaign. ## OpenAPI ````yaml /openapi.json post /public/v1/campaign-service/campaigns/{campaign-id}/bids 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/{campaign-id}/bids: post: tags: - Campaign API summary: Create Campaign Bids description: Endpoint to create a bid for a campaign. operationId: create_bids parameters: - name: campaign-id in: path required: true schema: type: string format: uuid description: The ID of the campaign. description: The ID of the campaign. - name: skip_existing_bids in: query required: false schema: type: boolean description: >- Skip creating bids that already exist. Existing bids will not be updated and will not be returned in the response. default: false description: >- Skip creating bids that already exist. Existing bids will not be updated and will not be returned in the response. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_BidCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_PublicBidsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_HTTPValidationError' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_BidCreateRequest: properties: bids: items: $ref: '#/components/schemas/Advanced_APIs_BidCreate' type: array maxItems: 500 minItems: 1 title: Bids description: An array of bids to be created. type: object required: - bids title: BidCreateRequest Advanced_APIs_PublicBidsResponse: properties: hasMore: type: boolean title: Hasmore description: Whether this is the last page of results or not. next: description: The parameters that should be used to fetch the next page. oneOf: - $ref: '#/components/schemas/Advanced_APIs_Next' - type: 'null' bids: items: $ref: '#/components/schemas/Advanced_APIs_Bid' type: array maxItems: 500 title: Bids description: An array of bids. type: object required: - hasMore - bids title: PublicBidsResponse description: The public response body of the bids endpoints. 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_Next: properties: offset: type: integer format: int32 title: Offset description: How many items to skip from the beginning of the list. limit: type: integer format: int32 title: Limit description: How many items to return. type: object required: - offset - limit title: Next Advanced_APIs_Bid: properties: bidId: type: string format: uuid title: Bidid description: The ID of the bid 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' description: The type of entity this bid will be targeting. isActive: type: boolean title: Isactive description: Whether the bid is active. triggers: items: oneOf: - $ref: '#/components/schemas/Advanced_APIs_KeywordTrigger-Output' - $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-Output' 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 title: Triggers description: >- A list of objects that trigger the appearance of this bid on an auction. 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' bidsBehaviorData: title: Bidsbehaviordata description: >- Deprecated. This field is always null. For behavioral data use reporting service. deprecated: true oneOf: - type: string - type: 'null' campaignId: type: string format: uuid title: Campaignid description: The ID of the campaign. formatProperties: description: '' oneOf: - $ref: '#/components/schemas/Advanced_APIs_BannerAd-Output' - type: 'null' state: $ref: '#/components/schemas/Advanced_APIs_BidState' description: The activity state of the bid. type: object required: - bidId - target - isActive - triggers - campaignId - state title: Bid description: >- Represents an auction bid for a specific entity and a specific maximum amount. 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_KeywordTrigger-Output: 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_BannerAd-Output: 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_BidState: type: string enum: - active - deactivated_manually - inactive_entity - deleted_entity - legacy_inactive - inactive_schedule title: BidState description: The activity state of a bid. 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 ````