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"
                    ]
                }
            }
        }
    ]
}

​
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.products.ids: An array of product IDs associated with the auction.

​
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
                        }
                    ],
                    "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:

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

​
Further Reading

For additional examples and use cases:

AttributionCreating an asset