Auctions

Usage

The Auction API runs an auction on a SmartLink and returns an updated destination URL for the link. You can use this API to write your own custom publisher Javascript tags. Be sure to read through the tutorial before proceeding.

Note

The Auction API does not require client authentication, but may be subject to rate-limiting if called an extreme number of times from the same origin.

Run Auction

Request

GET /api/v1/auction/
Query Param Type Description
a string Auction ID. This is the number at the end of your SmartLink. For example, the SmartLink https://shop-links.co/1522995078114976993 has the Auction ID 1522995078114976993.
t integer Cache-busting parameter. Set this to a randomly-generated number to prevent HTTP caching of the auction request and response.
uuid string Page Session UUID. The UUID v4 value that your client has generated for the current page session.

Response

Auction result data

Field Name Type Description
auction_result . id string A unique identifier for the result of the auction.
auction_result . product object Product information for the advertiser that won the auction.
auction_result . redirect_url string The new destination URL for the SmartLink.
auction_result . tracker_urls object Third-party event tracker URLs for this SmartLink placement. Your client is responsible for firing all trackers listed here when the applicable event(s) occur.
impression_pixel_url string The primary impression event tracker URL for this SmartLink placement. Your client is responsible for firing this tracker after receiving the auction response.

Product information (auction_result.product)

Auction API responses may provide the following information about the advertiser (retailer/merchant) and the product page that will be receiving the click on the rewritten SmartLink:

Field Name Type Description
id integer A unique identifier for the product that the destination URL refers to.
name string The name of the product being sold.
price string The price of the product being sold, in USD.
url string The raw URL of the product page, for display purposes. (Do not rewrite the SmartLink with this URL.)
image_url string The image URL of the product being sold, for display purposes.
is_in_stock boolean The stock status of the product being sold.
merchant . id integer A unique identifier for the advertiser.
merchant . canonical_host string The host part of the advertiser’s website URL, for display purposes.
merchant . name string The name of the advertiser.
merchant . url string The full URL for the advertiser’s home page.

Third-party event trackers (auction_result.tracker_urls)

Auction API responses may include the following set of third-party event trackers that apply to your SmartLink placement:

Event Tracker Type Event Description
impression Signals that at least one occurrence of this SmartLink has been loaded on the page. You may fire this event tracker immediately after receiving the auction response.
viewable_impression Fire this event tracker once any occurrence of this SmartLink is scrolled into view on the page.

Tracker URLs may include the template parameter {RAND}, which must be replaced with a randomly-generated number for cache-busting prior to firing the tracker.

Do NOT fire a third-party event tracker more than once per page for the same event, even if the same SmartLink appears multiple times on that page.

Example

GET https://api.bam-x.com/api/v1/auction/
    ?a=1629223267830557131
    &t=1517261651
    &uuid=8132ac19-109a-466e-8037-540a9bd12798
HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": {
    "error": false,
    "status": 200
  },
  "data": [
    {
      "auction_result": {
        "id": "1629224701990881693",
        "auction_id": "1629223267830557131",
        "redirect_url": "https://api.bam-x.com/api/v1/redirect/?a=1629223267830557131&uid_bam=1629224701957143181&ar=1629224701990881693&url=https%3A%2F%2Fwww.amazon.com.example%2F&uuid=8132ac19-109a-466e-8037-540a9bd12798",
        "product": {
          "merchant": {
            "url": "https://www.amazon.com/",
            "canonical_host": "amazon.com",
            "id": 2186,
            "name": "Amazon"
          },
          "bamx_product_category_id": 3,
          "name": "Designer Handbag",
          "url": "https://www.amazon.com.example/product/1234",
          "image_url": "https://www.static.amazon.example/image/path/1234",
          "is_in_stock": true,
          "price": "299.99",
          "id": 8030310
        },
        "tracker_urls": {
          "viewable_impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=lv;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
            "https://ad.atdmt.com.example/1111?r={RAND}"
          ],
          "impression": [
            "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=li;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
            "https://ad.atdmt.com.example/2222?r={RAND}"
          ]
        }
      },
      "impression_pixel_url": "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?"
    }
  ]
}