Partner API

Requesting brand pages

Brand page endpoint

The brand pages platform uses standalone URL's and path's to the ad generation endpoints. You Technical Account Manager will provide your base URL for sandbox and production environments.

Authorization

Authorization for the brand pages tool is bearer authentication. Your Technical Account Manager will be able to provide your bearer token for sandbox and production environments.

You will need to send the token in the header's as header 'Authorization: Bearer ${apiKey}

Request

To request a brand page, you will send a GET request to CitrusAd's brand-pageendpoint with the URL you are requesting for

curl --location --request GET '${URL}/api/v1/brand-page:static?url=${url}&retailer=${retailer}' \
--header 'Authorization: Bearer ${apiKey}

🚧

Sanitise URL query parameters

When requesting ads, you will need to remove any query parameters relevant to your site from the parameters sent to CitrusAd.

Inside the CitrusAd platform, we use this URL to fetch the exact page URL being requested. We will match https\:www.retailer.com/brand/lollipops-brand, but not if additional query parameters are specified.

Response

Depending on your brand page configuration, the segment responses will vary due to the both the segments integrated, and the brand page's template.

If you'd like to review the customisation capabilities, review the High level structure page.

Response Components

Container

The container serves the information for the entire brand page response, it also has a data array of objects, wherein the segment responses are held.

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
  ]
}

The data array will be populated with segments, subject to the brand page's configuration, the format of segments is detailed below.

Segments

Due to the customisation possibilities in the brand pages product, the exact response you receive will be subject to your configuration. Every segment will have an id and a name, in addition to the segment specific properties.

Banner segments

Inside of the data array, each segment is an object, like the below:

📘

Banner x specific attributes in the response are example only. The values in the response are configured per template and can be customised such as backgroundImage, brandLogo, or as you require.

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
    	  "headingText": "Banner For MasterFoods Beef Stroganoff with Shop Now button",
    	  "bannerText": "<strong>The Perfect Mid-Week Dinner</strong>",
    	  "bannerTextColour": "#fff",
   		  "heroImage": "https://storage.googleapis.com/assets-images/coke/2853856c8644",
  	    "heroImageAltText": "<i>Picture of the Dolmio Pasta Sauce</i>",
	      "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"
}

For more information on what's possible with banner segments, see High level structure.

Content segments

Inside of the data array, each segment is an object, like the below:

📘

heroText,heroTextColour, and heroSubText are examples for our example retailer. Each field can be named to your relevant field type such as paragraphText.

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
        "heroText": "<i>What a way to start your week</i>",
        "heroTextColour": "#000000",
        "heroSubText": "<i>What a way to start your week</i>",
}

For more information on what's possible with content segments, see High level structure.

Product segments

Inside of the data array, each segment is an object, like the below:

📘

This response format is fixed and not subject to customisation

 {
      "id":  "988dc393-a37a-421c-9b08-25f0f9e575f8",
      "name": "my-products",
      "productSelection": [
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 3,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 2,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 1,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        }
      ]
    }

📘

Product information

Much like the standard product ad integration, CitrusAd does not serve product attributes such as name, pricing, and image. This will need to be fetched from an internal product information server (or similar) on the retailer's infrastructure.

Whilst this is additional integration effort, this ensures there is no dependency on Citrus when updating and changing pricing information, as well as any automated graphics such as on special, 20% off, or similar content being dependent on CitrusAd.

For more information on what's possible with product segments, see High level structure.

Interpreting the response

In the response, each segment has an id and a name. These will be unique to a segment within a template. You can use these to identify different types of components, such as the type of banner, or the type of content and align it to where you inject it.

Example response

Here's an example of a brand page response for a template with one banner, one content, and one product segment would appear like.

📘

CUSTOM_ID_N is an example for a retailer defined ID such as paragraphText.

Response

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_ID_1": "string",
      "CUSTOM_ID_2": "string",
      "CUSTOM_ID_3": "string"
    },
    {
      "id":  "string",
      "name": "string",
      "productSelection": [
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        }
      ]
    },
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_TEXT_FIELD_ID_1": "VALUE",
      "CUSTOM_COLOUR_FIELD_ID_1": "VALUE",
      "CUSTOM_TEXT_FIELD_ID_2": "VALUE",
    }
  ]
}

Interested to see other templates and examples? View Example brand page templates.