> ## 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 auctions > Use the `/auctions` endpoint to create auctions. Each batch of auction requests can be a combination of sponsored listing auctions and banner auctions. Each auction type has a unique body schemas. ## OpenAPI ````yaml /openapi.json post /v2/auctions 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: /v2/auctions: post: tags: - Auctions summary: Create auctions description: > Use the `/auctions` endpoint to create auctions. Each batch of auction requests can be a combination of sponsored listing auctions and banner auctions. Each auction type has a unique body schemas. operationId: createAuctions requestBody: description: > The information describing what will be auctioned. Topsort will run an auction for each batched auction request, for which products' bids will compete against each other. content: application/json: examples: default: summary: Basic listings auction value: auctions: - type: listings slots: 2 products: ids: - p_PJbnN - p_ojng4 externalDemand: summary: Listings auction with external demand (e.g., Criteo) value: auctions: - type: listings slots: 3 products: ids: - p_PJbnN - p_ojng4 - p_8VKDt demandSources: - source: criteo bids: - chargeType: CPC entity: type: product id: p_PJbnN bidAmount: 0.5 metadata: clickUrl: https://example.com/click - chargeType: CPC entity: type: product id: p_ojng4 bidAmount: 0.35 metadata: clickUrl: https://example.com/product/ojng4 schema: type: object properties: auctions: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionRequest minItems: 1 maxItems: 5 example: - type: listings slots: 2 products: ids: - p_PJbnN required: true responses: '201': description: > The auction results. The list of winners will contain at most `slots` entries per auction. It may contain fewer or no entries at all if there aren't enough products with usable bids, that is, a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc. content: application/json: schema: type: object properties: results: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionResult minItems: 1 maxItems: 5 example: - resultType: listings winners: [] error: false required: - results examples: listingsAndBanners: summary: Listings and banner auction results value: results: - resultType: listings winners: - rank: 1 type: product id: p_Mfk11 resolvedBidId: >- WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0== campaignId: 82588593-85c5-47c0-b125-07e315b7f2b3 error: false - resultType: listings winners: - rank: 1 type: product id: p_Mfk15 resolvedBidId: >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= campaignId: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 - rank: 2 type: product id: p_PJbnN resolvedBidId: >- WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= campaignId: a72e4e43-55b5-4d08-81bb-cbb57df59c72 error: false - resultType: banners winners: - rank: 1 type: product id: p_PJbnN resolvedBidId: >- WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd campaignId: 1156ef4e-0109-4190-ac97-4436c82358d2 asset: - url: >- https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png content: headingText: >- A banner for Topsort with a product image and a shop now button bannerText: Topsort has the best tech! bannerTextColour: 48a94c heroImage: >- https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574 heroImageAltText: Topsort product image error: false empty: summary: Empty auction (no winners) value: results: - resultType: listings winners: [] error: false externalDemand: summary: External demand (Criteo + Topsort winners) value: results: - resultType: external_demand_listings winners: - rank: 1 type: product id: p_PJbnN resolvedBidId: >- WyJiX1BKYm5OIiwiY3JpdGVvIiwiQ1BDIiwibGlzdGluZ3MiXQ== demandSource: criteo metadata: clickUrl: https://example.com/click - rank: 2 type: product id: p_Mfk15 resolvedBidId: >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= demandSource: topsort campaignId: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 error: false '400': $ref: '#/components/responses/Topsort_Endpoints_v2_API_Reference_BadRequest' '401': $ref: >- #/components/responses/Topsort_Endpoints_v2_API_Reference_UnauthorizedError security: - Topsort_Endpoints_v2_API_Reference_HTTPBearer: [] components: schemas: Topsort_Endpoints_v2_API_Reference_AuctionRequest: description: Describes the intent of running a single auction. oneOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuction - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersAuction discriminator: propertyName: type Topsort_Endpoints_v2_API_Reference_AuctionResult: description: >- Base auction result schema supporting different auction types through discriminator. discriminator: propertyName: resultType mapping: listings: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult banners: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersAuctionResult empty: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult external_demand_listings: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsAuctionResult oneOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersAuctionResult - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsAuctionResult - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuction: title: Sponsored Listing type: object description: > Describes the intent of running a sponsored listings auction. Exactly **one** of the following fields must be set: * `products` * `category` The optional `demandSources` field enables external demand sources (e.g., Criteo) to participate in the auction. External demand is restricted to listings auctions only. properties: type: type: string const: listings description: Discriminator for the listings auction. slots: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_SlotsCount' category: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionCategory searchQuery: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_SearchQuery' products: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Products' geoTargeting: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_GeoTargeting' opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' placementId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_PlacementId' page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' filter: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_AttributesFilter demandSources: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_DemandSource description: > External demand sources participating in the auction. Total bids across all demand sources cannot exceed 100. This field is optional and requires additional integration and configuration. required: - type - slots examples: - type: listings slots: 2 products: ids: - p_PJbnN - p_ojng4 - p_8VKDt - p_Mfk15 geoTargeting: location: New York - type: listings slots: 2 products: ids: - p_PJbnN - p_ojng4 demandSources: - source: criteo bids: - chargeType: CPC entity: type: product id: p_PJbnN bidAmount: 0.5 metadata: clickUrl: https://example.com/click Topsort_Endpoints_v2_API_Reference_BannersAuction: title: Banner Auction type: object description: | Describes the intent of running a banner ads auction. * For **Landing Page** banners, `category` and `searchQuery` must be empty. * For **Category** banners, the `category` field must be set. * For **Keywords** banners, the `searchQuery` field must be set. properties: type: type: string const: banners description: Discriminator for the banner auction. slots: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_SlotsCount' category: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionCategory searchQuery: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_SearchQuery' device: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Device' geoTargeting: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_GeoTargeting' slotId: type: string description: >- The ID of the banner placement for which this auction will be run for. minLength: 1 products: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Products' opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' placementId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_PlacementId' page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' required: - type - slots - slotId examples: - type: banners slots: 1 slotId: categories-ribbon-banner category: id: c_yogurt Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult: title: Sponsored Listings description: >- The result of a sponsored listings auction, containing winning product listings. type: object properties: resultType: type: string winners: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsWinner description: > Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error. error: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag' required: - winners - error - resultType Topsort_Endpoints_v2_API_Reference_BannersAuctionResult: title: Banner Auction description: The result of a banner auction, containing winning banner ads. type: object properties: resultType: type: string winners: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersWinner description: > Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error. error: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag' required: - winners - error - resultType Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult: title: Empty Auction description: >- An auction result with no winners, typically when no eligible bids are available. type: object properties: resultType: type: string winners: type: array maxItems: 0 error: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag' required: - winners - error - resultType Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsAuctionResult: title: Sponsored Listings with External Demand description: >- The result of a sponsored listings auction with external demand, containing winning product listings. type: object properties: resultType: type: string winners: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsWinner description: > Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error. error: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag' required: - winners - error - resultType examples: - resultType: listings winners: - rank: 1 type: product id: p_PJbnN resolvedBidId: WyJiX1BKYm5OIiwiY3JpdGVvIiwiQ1BDIiwibGlzdGluZ3MiXQ== demandSource: criteo metadata: clickUrl: https://example.com/click - rank: 2 type: product id: p_Mfk15 resolvedBidId: >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= demandSource: topsort campaignId: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 error: false Topsort_Endpoints_v2_API_Reference_Error: description: >- Error response object containing error code, message, and documentation URL. type: object required: - errCode properties: errCode: type: string description: A short string uniquely identifying the problem. enum: - bad_request - empty_request - internal_server_error - invalid_api_key - invalid_auction_id - invalid_demand_source - invalid_event_type - invalid_external_bid - invalid_external_demand_ad_type - invalid_promotion_type - invalid_session - missing_auctions - missing_context - missing_placement - missing_product_id - missing_promotion_type - missing_purchased_at - missing_session - missing_slot_id - missing_slots - no_products - no_purchase_items - purchase_item_quantity_less_or_equal_than_zero - resolved_bid_id_not_found - too_few_impressions - too_few_slots - too_many_auctions - too_many_external_bids - unauthorized_external_demand examples: - bad_request - no_products docUrl: type: string format: uri description: >- A link to a documentation page providing more information about the error. examples: - https://api.docs.topsort.com/reference/errors message: type: string description: > Human-readable explanation of or details about the error. The string for a given error may change over time; code should not parse or dispatch based on particular values for this field. examples: - could not find the provided resolved bid id Topsort_Endpoints_v2_API_Reference_SlotsCount: type: integer format: int32 description: Specifies the maximum number of auction winners that should be returned. minimum: 1 maximum: 40 Topsort_Endpoints_v2_API_Reference_AuctionCategory: description: >- Represents one or more categories for auction targeting. Can be a single category, multiple categories, or category disjunctions. oneOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SingleCategory - type: object title: Multiple Categories description: A set of categories for the purpose of running an auction. required: - ids properties: ids: type: array description: > An array containing the category IDs of the bids that will participate in an auction. In order to participate in an auction, a bid product must belong to **all** of the categories provided in the auction request. items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID minItems: 1 examples: - - c_men_clothing - c_shoes - type: object title: Category Disjunctions description: >- Multiple disjunctions of categories for the purpose of running an auction. required: - disjunctions properties: disjunctions: type: array description: > An array of disjunctions. In order to participate in an auction, a bid product must belong to at least one of the categories of the disjunction provided in the auction request. items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryDisjunction minItems: 1 maxItems: 5 examples: - - - c_red - - c_blue Topsort_Endpoints_v2_API_Reference_SearchQuery: type: string description: The search string provided by a user. Topsort_Endpoints_v2_API_Reference_Products: required: - ids type: object description: | List of products for the purpose of running an auction. properties: ids: type: array description: > An array of product IDs that should participate in the auction. We recommend sending no more than 500 products per auction. items: type: string description: > The marketplace's ID of a product which will participate in the auction. These ID must match those in the catalog integration with Topsort. examples: - p_SA0238 minLength: 1 minItems: 1 maxItems: 10000 qualityScores: type: array description: > An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. If given, these values will be combined with our internal quality scores to provide a score that better represents the relevance of the participating products. Note that the length of this array must be the same as the length of the `ids` array and that the values must be greater than 0 and less than or equal to 1. items: type: number maximum: 1 exclusiveMinimum: 0 minimum: 0 examples: - 0.75 format: double minItems: 1 maxItems: 10000 Topsort_Endpoints_v2_API_Reference_GeoTargeting: type: object description: >- An object describing geographical information associated with this auction. required: - location properties: location: description: The location this auction is being run for. type: string examples: - New York Topsort_Endpoints_v2_API_Reference_OpaqueUserID: type: string description: >- The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests. examples: - 71303ce0-de89-496d-8270-6434589615e8 Topsort_Endpoints_v2_API_Reference_PlacementId: type: integer format: int32 description: The marketplace's ID of the placement where the ad will appear. Topsort_Endpoints_v2_API_Reference_Page: description: Information about the page where an auction or event occurs. type: object title: Page required: - type - pageId properties: type: type: string enum: - home - category - PDP - search - cart - other description: Type of page. examples: - category value: oneOf: - type: string description: Detail of the page, depending on the type examples: - electronics - type: array items: type: string description: Only valid for type cart. Items on the cart examples: - coffee - cookies - apples minItems: 1 pageId: type: string description: Identifies the page examples: - /category/electronics Topsort_Endpoints_v2_API_Reference_AttributesFilter: type: object title: AttributesFilter description: > Use product attributes to filter auction bids. This feature requires additional integration and configuration. properties: operator: type: string description: >- Filter operator type. The value can be `and` (has all) or `or` (has any). enum: - and - or attributes: type: array description: > Attributes used for filtering in `key:value` format. The attribute name and value are limited to 40 characters each. maxItems: 5 items: type: string maxLength: 81 examples: - color:red - material:leather - size:32 Topsort_Endpoints_v2_API_Reference_DemandSource: type: object description: External demand source participating in the auction. required: - source - bids properties: source: type: string enum: - criteo description: Identifier for the demand source. bids: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalBid description: > Array of external bids. Total count across all demand sources must not exceed 100. Topsort_Endpoints_v2_API_Reference_Device: type: string description: The device for which the ads are meant for. enum: - desktop - mobile default: desktop Topsort_Endpoints_v2_API_Reference_SponsoredListingsWinner: description: >- A winning bid in a sponsored listings auction with product and campaign details. type: object required: - rank - type - id - resolvedBidId - campaignId properties: rank: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerRank' type: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType - enum: - product - vendor - brand - url id: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerID' examples: - p_Mfk15 resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID campaignId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_CampaignId' Topsort_Endpoints_v2_API_Reference_ErrorFlag: type: boolean description: A boolean indicating whether this auction was resolved successfully. examples: - false - true Topsort_Endpoints_v2_API_Reference_BannersWinner: description: A winning bid in a banner auction with asset and campaign details. type: object required: - rank - type - id - resolvedBidId - asset properties: rank: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerRank' type: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType - enum: - product - vendor - brand - url id: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerID' examples: - p_Mfk15 resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID campaignId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_CampaignId' asset: description: The list of available sources for a banner. type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_AssetSource minItems: 1 Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsWinner: type: object required: - rank - type - id - resolvedBidId - demandSource properties: rank: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerRank' type: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType' enum: - product id: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerID' resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID demandSource: type: string enum: - criteo - topsort campaignId: type: string description: >- The ID of the campaign that won the auction. This is omitted for external winners. examples: - 82588593-85c5-47c0-b125-07e315b7f2b3 metadata: type: object additionalProperties: true description: > Pass-through metadata from the request for external winners (e.g., beacon URL, click URL). This is omitted for internal winners. examples: - beaconUrl: https://some.url.com/beacon clickUrl: https://some.url.com/click Topsort_Endpoints_v2_API_Reference_SingleCategory: type: object title: Single Category description: A category for the purpose of running an auction. required: - id properties: id: type: string description: The category ID of the bids that will participate in an auction. minLength: 1 examples: - c_yogurt Topsort_Endpoints_v2_API_Reference_CategoryID: type: string description: A category ID. minLength: 1 examples: - c_electronics Topsort_Endpoints_v2_API_Reference_CategoryDisjunction: type: array description: > An array of category IDs, describing a category disjunction. A bid entity must belong to at least one of the categories in the disjunction in order to participate in the auction. items: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID' minItems: 1 Topsort_Endpoints_v2_API_Reference_ExternalBid: type: object description: A bid from an external demand source participating in the auction. required: - chargeType - entity - bidAmount properties: chargeType: type: string enum: - CPC description: The charging model for this bid. entity: type: object required: - type - id properties: type: type: string enum: - product description: Entity type. External bids currently only support product. id: type: string description: The marketplace's ID of the entity. bidAmount: type: number description: Bid amount in marketplace currency. metadata: type: object additionalProperties: true description: Optional free-form data (e.g., beacon URL, click URL). Topsort_Endpoints_v2_API_Reference_WinnerRank: type: integer format: int32 description: >- The rank/position of this winner in the auction results, with 1 being the highest. minimum: 1 Topsort_Endpoints_v2_API_Reference_WinnerType: type: string description: The target type of the winning bid. Topsort_Endpoints_v2_API_Reference_WinnerID: type: string description: >- The marketplace's ID of the winning entity, depending on the target of the campaign. Topsort_Endpoints_v2_API_Reference_ResolvedBidID: type: string description: An opaque Topsort ID to be used when this item is interacted with. examples: - >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= Topsort_Endpoints_v2_API_Reference_CampaignId: type: string description: The ID of the campaign that won the auction. examples: - 82588593-85c5-47c0-b125-07e315b7f2b3 Topsort_Endpoints_v2_API_Reference_AssetSource: description: A source available for an asset (banner or video). type: object properties: url: type: string format: uri description: > A vendor provided asset that the marketplace has to use as a banner. The asset will be served by Topsort's CDN. Note: When the content field is part of the response, the url links to an asset with the same JSON object available on the content object. content: type: object additionalProperties: true description: > A flexible JSON object with key-value pairs that map to the asset's filled content template. The template can be customized by the marketplace. Note: When the content field is part of the response, the url links to an asset with the same JSON object available on the content object. examples: - headingText: A banner for Topsort with a product image and a shop now button bannerText: Topsort has the best tech! bannerTextColour: 48a94c heroImage: >- https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574 heroImageAltText: Topsort product image required: - url responses: Topsort_Endpoints_v2_API_Reference_BadRequest: description: HTTP status codes as registered with IANA. content: application/json: schema: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Error' Topsort_Endpoints_v2_API_Reference_UnauthorizedError: description: Access token is missing or invalid securitySchemes: Topsort_Endpoints_v2_API_Reference_HTTPBearer: description: >- A valid API key generated in Topsort's UI. Use a TSE API key for calls to Auctions or Events API. scheme: bearer type: http ````