Ad Request Endpoint

We currently support either GET or POST variations of the ad request endpoint.

GET

Base URL:

https://servedbyadbutler.com/adserve/;ID=123456;setID=123456;type=pdb_query_get

Parameters:

1. pdb_search - A string of text to search with for relevancy results.ex. fancy sneakers
2. pdb_params - JSON String. A json string representing the key-value pairs to further filter results ex. {"product_type":"SHOES"}
3. pdb_limit - Integer. Limits the number of results that will be returned. ex. 1
4. adb_uid - String. A generic anonymous user id (used to track client interactions on a retailer site)
5. udb_uid - The unique identifier for the user requesting the ad. This corresponds to the id_name_field in this publisher’s User DB.
6. ip - The client ip address
7. ua -The client's user agent
8. referrer - The referring url of the request
9. pdb_source - The source id for this request which corresponds to the id of source created by this publisher
10. bid_floor_cpm -Overrides the bid_floor_cpm of the zone. It is assumed to be in the publisher's currency.
11. bid_floor_cpc - Overrides the bid_floor_cpc of the zone. It is assumed to be in the publisher's currency.
12. pdb_identifiers - An optional list of SKUs used to filter eligible campaigns.

Example URL (this is live on a test account):

https://servedbyadbutler.com/adserve/;ID=164128;setID=595468;type=pdb_query_get;pdb_search=shoes;pdb_params=%7B%22type_name%22:%22APPAREL%22%7D;pdb_limit=1

POST

Base URL:

https://servedbyadbutler.com/adserve/;ID=123456;setID=123456;type=pdb_query

JSON Structure:

1. search - A string of text to search with for relevancy results.ex. fancy sneakers
2. source - The source id for this request, which corresponds to the id of source created by this publisher.
3. params - A set of key-value pairs used to further filter results. ex. {"product_type":"SHOES"}
4. limit - Integer. Limits the number of results that will be returned. ex. 1
5. source - The source id for this request which corresponds to the id of source created by this publisher
6. adb_uid - String. A generic anonymous user id (used to track client interactions on a retailer site)
7. udb_uid - The unique identifier for the user requesting the ad. This corresponds to the id_name_field in this publisher’s User DB.
8. ip -The client ip address
9. ua - The client's user agent
10. referrer - The referring url of the request
11. bid_floor_cpm - Overrides the bid_floor_cpm of the zone. It is assumed to be in the publisher's currency.
12. bid_floor_cpc - Overrides the bid_floor_cpc of the zone. It is assumed to be in the publisher's currency.
13. identifiers - An optional list of SKUs used to filter eligible campaigns.

Example JSON:

{
    "search": "fancy sneakers",
    "source": 12345,
    "params": {
        "product_type": "SHOES"
    },
    "limit": 1,
    "source": PUBLISHER_SOURCE_ID,
    "adb_uid": "b477d170-e2a6-476d-9936-4e47da160d9a",
    "udb_uid": "e4b42f2a-bba2-436f-8151-ac6604b19e1c",
    "_abdk_json" : {
        "gender" : "male",
        "age" : "25"
    },
    "ip": "70.66.129.0",
    "ua": "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Testing/1.0",
    "referrer": "https://example.com",
    "bid_floor_cpm": 16
}

Sample Response

{
  "status": "success",
  "items": [
    {
      "item": {
          "id": "123456789",
          "title": "CoolShoes Fancy Sneakers",
          "brand": "CoolShoes",
          "description": "CoolShoes Fancy Sneakers makes you run faster, jump higher, and leap further.",
          "price": "99.99",
          "product_url": "https://...",
          "thumbnail_url": "https://...",
          "product_type": "SHOES",
          "product_subtype": "CHILDRENS_SHOES",
          "seller_id": "10001234",
          "vendor_id": "kzNjc1MzNlZTA4Y2U",
          "upc": "123123123123",
          "rating": "4.5"
      },
      "beacons": [
        {
          "type": "eligible_impression",
          "url": "https://..."
        },
        {
          "type": "viewable_impression",
          "url": "https://..."
        },
        {
          "type": "click",
          "url": "https://..."
        }
      ]
    }
  ]
}