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

# Sponsored brands

> Learn how to use the Sponsored Brands auctions API to create auctions for brand promotions.

The Sponsored Brands Auctions API allows you to run auctions to promote brands using assets, text, and associated products.

## Before You Begin

To use the Sponsored Brand Auctions API, ensure you have completed the following:

1. [Obtain an API key](/en/api-reference/authentication#obtaining-an-api-key) for authentication.
2. [Create several campaigns](/en/knowledge-base/ad-platform/campaign-creation/), to have bids available for the auctions.

## Request

The `/auctions/sponsored-brand` endpoint allows you to run auctions for sponsored brand placements.

For the full specification of this endpoint, refer to the [API documentation](/en/api-reference/auctions/create-sponsored-brand-auctions).

### Example Request

```json theme={null}
{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "products": {
          "ids": ["1", "8"]
        }
      }
    }
  ]
}
```

### Example Request with Geolocation Targeting

```json theme={null}
{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "searchQuery": "electronics"
      },
      "geoTargeting": "new-york",
      "opaqueUserId": "user-123"
    }
  ]
}
```

### Example Request with Attributes Filter

```json theme={null}
{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "searchQuery": "running shoes"
      },
      "filter": {
        "operator": "or",
        "attributes": ["brand:nike", "category:66e895c424dd8e36c1318b0c"]
      },
      "opaqueUserId": "user-123"
    }
  ]
}
```

The `filter` field narrows the auction to ads whose attributes match the given `key:value` pairs. Use `operator: "or"` to keep ads matching **any** of the attributes (broader match), or `operator: "and"` to keep only ads matching **all** of them (stricter match). Ads that don't match are excluded before ranking, so filtered-out bids never win or get charged. This feature requires additional integration and configuration — contact your Topsort representative to enable it.

#### Key Fields:

* **`auctions`**: An array containing auction objects.
* **`winners`**: The maximum number of winners for the auction.
* **`placementId`**: The ID of the placement where the ad will appear.
* **`triggers`**: Targeting criteria including:
  * **`products.ids`**: An array of product IDs associated with the auction.
  * **`searchQuery`**: Search terms for keyword-based targeting.
  * **`category.id`**: Product category for broader targeting.
* **`geoTargeting`**: *(Optional)* Geographic location identifier for location-based campaign filtering.
* **`opaqueUserId`**: *(Optional)* Anonymous user identifier for personalization and enhanced targeting.
* **`filter`**: *(Optional)* Restricts the auction to ads whose attributes match the given `key:value` pairs.
  * **`operator`**: `or` (match any attribute) or `and` (match all attributes).
  * **`attributes`**: Up to 5 `key:value` strings. Both the key and value are limited to 40 characters each.

***

## Response

<Warning>
  **Do not cache this response** or its results. Auctions must remain unique per page view to ensure proper operation.

  Caching may result in repeated results for multiple users or sessions.
</Warning>

If no [request errors](https://topsort.mintlify.app/api-reference/errors) occur, the endpoint returns the results of the auction.

### Response With Winners

Example response when winners are found:

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "resolvedBidId": "ChAGc-G66Wt7LKQEOcW8VBdIEhABjz_zDXx7db-ZYpxiwJ3DGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATEQATDrrg8",
          "productId": "1",
          "title": "Brand Example Promo 1",
          "assets": [
            {
              "url": "https://assets.hosted.topsort.com/5bcccb92e5eaaa73ce9fcc545e944865bf70e9b60e5a048979769282450343c4/example-banner-1.png",
              "role": "image",
              "contentType": "image/png",
              "contentLength": 33902,
              "width": 920,
              "height": 920
            },
            {
              "url": "https://assets.hosted.topsort.com/c27c9cd94badc90fb50827e144dfacb2f51a601560905b950f525cec725ea85f/example-logo-1.png",
              "role": "logo",
              "contentType": "image/png",
              "contentLength": 80648,
              "width": 264,
              "height": 264
            }
          ],
          "campaignId": "018f3ff3-0d7c-7b75-bf99-629c62c09dc3"
        },
        {
          "rank": 2,
          "resolvedBidId": "ChAGc-G66Wt7LKQEOcW8VBdIEhABk0pue7N5wYmzE04uO_iOGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATgQATDrrg8",
          "productId": "8",
          "title": "Brand Example Promo 2",
          "assets": [
            {
              "url": "https://assets.hosted.topsort.com/c049a46d834ab071cdde63e401d4efcd554e1a124f05c4ba9b3743fed2d43c4b/example-banner-2.jpeg",
              "role": "image",
              "contentType": "image/jpeg",
              "contentLength": 4505,
              "width": 403,
              "height": 125
            },
            {
              "url": "https://assets.hosted.topsort.com/db41a8b8b22c5ed9091f9f154b552b6bc1d1dbeb85059190f1c3b202977938f1/example-logo-2.png",
              "role": "logo",
              "contentType": "image/png",
              "contentLength": 34747,
              "width": 140,
              "height": 160
            }
          ],
          "campaignId": "01934a6e-7bb3-79c1-89b3-134e2e3bf88e"
        }
      ],
      "error": false
    }
  ]
}
```

### Response With No Winners

Example response when no winners are found:

```json theme={null}
{
  "results": [
    {
      "winners": [],
      "error": false
    }
  ]
}
```

***

## **Further Reading**

For additional examples and use cases:

* [Create Sponsored Listings Auctions](/en/api-reference/examples/sponsored-listings)
* [Create Sponsored Banner Auctions](/en/api-reference/examples/sponsored-banners)

***