Partner API

Requesting brand pages

👍

When integrating brand pages, you should automate the requesting of ads to CitrusAd without any additional development effort per brand page. CitrusAd advises you build a templated mechanism to request ads from CitrusAd when a customer lands on a specific type of page.

For example, when the customer reaches www.retailer.com/brandpage/grocery-brand-page-summer, you will extract that from this page, the CitrusAd brand page ID is grocery-brand-page-summer.

By implementing this type of mechanism, it means that all brand page generation can be controlled within the CitrusAd platform.

Requesting ads

When requesting for a brand page you will make three requests. Each endpoint will return the relevant page content for you to render. You will make requests to
• /generate for the products required
• /generate/brandpage for the page heading and page text content
• /bannerx for the banner content on your brand page.

From the three endpoints, you will be able to fill your brand page with content.

Brand Page ID / URL

In the CitrusAd ad wizard, there is a stage wherein the user enters the brand page URL (ID) they wish for their campaign.

756

This URL is configured in the CitrusAd portal by the user, and will align with the real URL of their site.

When requesting brand pages, you will specify a placement of brandpage in your ad request. Depending on the endpoint being interacted with, you will specify a filter of brandpage:<brandPageId> or specify a brandPageId. This filter is the individual identifier of the brand page.

📘

If a brand page campaign isn’t set up for your supplied brand page, you will receive a 200 and not receive the content in the response - this is expected behaviour. If you believe you should be receiving content, check that a valid and active brand page campaign is configured.

Product ads

You will send a request to the /generate endpoint, which will retrieve your page's product ads. 

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "brandpage",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["brandpageurl:<URL_SUFFIX>"]
    ],
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 15               
}

You will receive a response that mirrors the typical product ad response, visible in Requesting product ads

Banner x ads

You will send a request to the /bannerx endpoint, which will retrieve your page's banner x ad.

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "brandpage",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b"
    "productFilters": [
         ["brandpageurl:<URL_SUFFIX>"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    }
    ]
}

You will receive a response that mirrors the typical banner x ad response.
You will receive a response that mirrors the typical product ad response, visible in Requesting product ads

Brand page content

You will send a request to the /generate/brandpage endpoint for.

POST $BASE_URL/v1/ads/generate/brandpage HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogId":"628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "placement":"brandpage",
    "brandPageId": "test-brand-page"
}

You will receive a response like the below:

{
    "content": {
        "pageContentText": "Page content text to render on your website",
        "pageHeaderText": "The page's heading text to render on your website"
    }
}

Request enhancements

We advise you to consider the below enhancements to improve your user experience.

Filtering by location

If you are synchronising location filters in your catalog, you can extend your context to provide the customer's store location in the productFilters, like the example below:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "brandpage",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["brandpageurl:<URL_SUFFIX>"],["location:Westenbury"]
    ],
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 15               
}