Requesting a Search Term Banner X Ad

Search term banner ads require a simple "context' to be sent to CitrusAd. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.
Banner X Ads use the /bannerx endpoint
You will receive your contentStandardId from CitrusAd once your content standard is generated.
Minimum Viable Context:
Below are the minimum values needed to generate a search term ad:
HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "customerId": "string",
    "sessionId": "string", 
    "catalogId": "string",
    "pageType": "string",
    "searchTerm": "string",
    "contentStandardId": "string",
    "bannerSlotIds": [
          {
            "slotId": "string",
      "maxNumberOfAds": number
     }
   ]
}
cURL
curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "customerId": "string",
    "sessionId": "string", 
    "catalogId": "string",
    "pageType": "string",
    "searchTerm": "string",
    "contentStandardId": "string",
    "bannerSlotIds": [
          {
            "slotId": "string",
      "maxNumberOfAds": number
     }
   ]
}'
Exemplar Context
Here is an example of a context for the pageType "Search":
HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     }
   ]
}
cURL
curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     }
   ]
}'
What Happens when an Ad Is Successfully Requested
When you successfully request an ad, you receive the following object:
HTTP
cURL
HTTP
HTTP/2 200
{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}
cURL
{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}
You may receive less fields within a banner object, this will occur when a banner is configured without all possible fields.
Filtered Searches & Multiple Banners
When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.
In this example, the user has searched for "chocolate" and navigated into the "Cupboard" category, and browsed further to "Confectionery". This is a new request and considered by CitrusAd as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.. The example below also requests 2 banner slot ids:
HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",    
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "productFilters": [
      ["category:cupboard", "category:confectionery"]
    ],
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Search_Single_Tile",
      "maxNumberOfAds": 1
     }
   ]
}
cURL
curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",    
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "productFilters": [
      ["category:cupboard", "category:confectionery"]
    ],
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Search_Single_Tile",
      "maxNumberOfAds": 1
     }
   ]
}'
As your customers filter deeper in their searches, your request will include more product filters
HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",    
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "productFilters": [
      ["category:cupboard", "category:confectionery", "category:chocolateBlocks",  "dietary:vegan", "priceRange:$1-3"]
    ],
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Search_Single_Tile",
      "maxNumberOfAds": 1
     }
   ]
}
cURL
curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",    
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "productFilters": [
      ["category:cupboard", "category:confectionery", "category:chocolateBlocks",  "dietary:vegan", "priceRange:$1-3"]
    ],
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Search_Single_Tile",
      "maxNumberOfAds": 1
     }
   ]
}'
What Happens when an Ad Is Successfully Requested
When you successfully request an ad, you receive the following object:
HTTP
cURL
HTTP
HTTP/2 200
{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        },
         {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Single_Tile",
            "banners": [
                {
                    "citrusAdId": "shotgun_8d6bd7aa780d2278cf743d95cbdcfb7d262c5ba0575446cba91b628720975bx",
                    "citrusCampaignName": "brandb-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Single_Tile",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerBrandA BrandAChocolateBlocks shop now button",
                    "bannerText": "<strong>You'll love BrandA's NEW Chocolate Blocks</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "BrandA product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for BrandA products",
                    "ctaLink": "retailer.com/everything/search/brand%20%a?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "BrandA Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}
cURL
{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        },
         {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Single_Tile",
            "banners": [
                {
                    "citrusAdId": "shotgun_8d6bd7aa780d2278cf743d95cbdcfb7d262c5ba0575446cba91b628720975bx",
                    "citrusCampaignName": "brandb-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Single_Tile",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerBrandA BrandAChocolateBlocks shop now button",
                    "bannerText": "<strong>You'll love BrandA's NEW Chocolate Blocks</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "BrandA product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for BrandA products",
                    "ctaLink": "retailer.com/everything/search/brand%20%a?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "BrandA Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}
Using Session Ids for Order Attribution
If you are planning on using sessionIds as your method of order attribution, you will need to send a sessionId in your ad generation requests:
HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "productFilters": [
      ["category:cupboard", "category:confectionery", "category:chocolateBlocks",  "dietary:vegan", "priceRange:$1-3"]
    ],
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Search_Single_Tile",
      "maxNumberOfAds": 1
     }
   ],
    "customerId": "wertg5432a",  
     "sessionId": "23dn3923-323d"
}
cURL
curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Search",
    "searchTerm": "chocolate",
    "productFilters": [
      ["category:cupboard", "category:confectionery", "category:chocolateBlocks",  "dietary:vegan", "priceRange:$1-3"]
    ],
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Search_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Search_Single_Tile",
      "maxNumberOfAds": 1
     }
   ],
    "customerId": "wertg5432a",   
       "sessionId": "23dn3923-323d"
}'
If you are unsure of the strings displayed on this page. Take a look at the Reference page.
Banner X Ad Reference
/integration-guides/banner-x-ad-integration-guide/banner-x-reference
​
Requesting a Category Banner X Ad
Requesting a Home Page Banner X Ad
Last updated 7 months ago