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 for authentication.
2. Create several campaigns, 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.

Example Request

{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "products": {
          "ids": ["1", "8"]
        }
      }
    }
  ]
}

Example Request with Geolocation Targeting

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

Example Request with Attributes Filter

{
  "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

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.

If no request errors occur, the endpoint returns the results of the auction.

Response With Winners

Example response when winners are found:

{
  "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
            }
          ],
          "content": {
            "aiGeneratedAssets": [
              "https://assets.hosted.topsort.com/5bcccb92e5eaaa73ce9fcc545e944865bf70e9b60e5a048979769282450343c4/example-banner-1.png"
            ]
          },
          "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
    }
  ]
}

AI-generated asset declarations

content.aiGeneratedAssets is an optional array containing the URLs of image assets that the advertiser declared were generated or modified with AI. Match these URLs against the assets you render to determine which creatives carry an advertiser declaration.

Only positively declared assets are included.

Response With No Winners

Example response when no winners are found:

{
  "results": [
    {
      "winners": [],
      "error": false
    }
  ]
}

---

Further Reading

For additional examples and use cases:

• Create Sponsored Listings Auctions
• Create Sponsored Banner Auctions

---