Requesting a Search Term Banner 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 Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

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/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
"pageType": "Search",
"catalogId": "$MY_CATALOG_ID",
"searchTerm": "string",
"contentStandardId": "string",
"bannerSlotIds": ["string"],
"maxNumberOfAds": number
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
"pageType": "Search",
"catalogId": "$MY_CATALOG_ID",
"searchTerm": "string",
"contentStandardId": "string",
"bannerSlotIds": ["string"],
"maxNumberOfAds": number
}'

Exemplar Context

Here is an example of a context for the pageType "Search":

HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Chocolate",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner"],
"maxNumberOfAds": 0
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Chocolate",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner"],
"maxNumberOfAds": 0
}'

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": [],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Search_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search banner for brandx chocolate",
"text": "",
"gtins": [
"2899049P",
"9891566P",
"2902620P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
}
],
"products": []
}
cURL
{
"ads": [],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "dc5aff9a-e0b1-4bf8-999f-393329b4afae",
"slotId": "Search_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "retailer.com/linkforwardedurl",
"altText": "Search banner for brandx chocolate",
"text": "",
"gtins": [
"2899049P",
"9891566P",
"2902620P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
}
],
"products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of search terms and necessary filters.

The products field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

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 navigated to the Red Wine category within their search, and filtered their browsing to "Shiraz" Red Wines. 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/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz"]
],
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner", "Tile_Banner"],
"maxNumberOfAds": 0
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz"]
],
"maxNumberOfAds": 3
}'

As your customers filter deeper in their searches, your request will include more product filters

HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
],
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner", "Tile_Banner"],
"maxNumberOfAds": 0
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
],
"maxNumberOfAds": 0
}'

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": [],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Search_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search banner for brandx red wine",
"text": "",
"gtins": [
"2899049P",
"9891566P",
"2902620P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
},
{
"id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Tile_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search tile banner for brandy red wine",
"text": "",
"gtins": [
"2790492P",
"6902690P",
"8891466P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
}
],
"products": []
}
cURL
{
"ads": [],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Search_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search banner for brandx red wine",
"text": "",
"gtins": [
"2899049P",
"9891566P",
"2902620P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
},
{
"id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Tile_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search tile banner for brandy red wine",
"text": "",
"gtins": [
"2790492P",
"6902690P",
"8891466P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
}
],
"products": []
}

Requesting Product Ads

To request Product Ads and Banner Ads in the same request, use the maxNumberOfAds field to specify the number of Product Ads requested.

Below is an example requesting 3 Product Ads and 2 Banner Ads

HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
],
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner", "Tile_Banner"],
"maxNumberOfAds": 3
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
],
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner", "Tile_Banner"],
"maxNumberOfAds": 3
}'

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": [
{
"id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
"gtin": "2899049P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516943179Z"
},
{
"id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
"gtin": "9891566P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516948637Z"
},
{
"id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
"gtin": "2902620P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Search_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search banner for brandx red wine",
"text": "",
"gtins": [
"2899049P",
"9891566P",
"2902620P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
},
{
"id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Tile_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search banner for brandy red wine",
"text": "",
"gtins": [
"2790492P",
"6902690P",
"8891466P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
}
],
"products": []
}
cURL
{
"ads": [
{
"id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
"gtin": "2899049P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516943179Z"
},
{
"id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
"gtin": "9891566P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516948637Z"
},
{
"id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
"gtin": "2902620P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Search_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search banner for brandx red wine",
"text": "",
"gtins": [
"2899049P",
"9891566P",
"2902620P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
},
{
"id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Tile_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Search banner for brandy red wine",
"text": "",
"gtins": [
"2790492P",
"6902690P",
"8891466P"
],
"expiry": "2019-12-10T01:46:07.518340479Z"
}
],
"products": []
}

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/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
],
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner", "Tile_Banner"],
"sessionId": "23dn3923-323d",
"maxNumberOfAds": 3
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"pageType": "Search",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "Wine",
"productFilters": [
["category:RedWine", "category:Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
],
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Search_Banner", "Tile_Banner"],
"sessionId": "23dn3923-323d",
"maxNumberOfAds": 3
}'

If you are unsure of the strings displayed on this page. Take a look at the Reference page.