Get a brand page

POST /v2/ian/bp

Retrieves a brand page that is associated with the display placement ad that is clicked by a customer. Send the click as the value for the slug field. The response returns a page URL, the top most banner, and an ordered list of brand page block ids that identify the blocks to appear in the page. Use the Get a brand page block endpoint to retrieve the block content.

Security

Name	In	Description
Authorization	header	The Authorization header with the bearer token acquired during authentication.

Parameters

Name	In	Type	Required	Description
X-Retailer-Id	header	string		The retailer slug. This is only required for a retailer with multiple banners. Retailers with single banners can leave this empty.

Request

Field	Type	Required	Description
slug	string		The slug of brand page.
page_view_id	string		Identifier associated with the page view. Must be a UUID (Universal Unique Identifier).
interaction_id	string		Identifier to associate brand page with the display ad. Must be a UUID (Universal Unique Identifier).
session_context	SessionContext		Context related to user session.
store_context	StoreContext		Context related to the selected store.

SessionContext Object

Field	Type	Required	Description
user_id	string		Unique user ID of the user performing the query. Maximum 50 characters.
user_ip	string		The IP address of the end user. Maximum 50 characters.
user_agent	string		The user agent of the device making the request. Maximum 50 characters.
test_only	boolean		When true, the campaigns created for Carrot Ads testing are guaranteed to participate in the ads auction along with other campaigns. Default is false.

StoreContext Object

Field	Type	Required	Description
location_code	string		The store location code used to perform the query. Maximum 100 characters.

Request examples

cURL

curl --request POST \
  --url https://connect-ian.instacart.com/v2/ian/bp \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Retailer-Id: string' \
  --data '{
  "slug": "string",
  "page_view_id": "string",
  "interaction_id": "string",
  "session_context": {
    "user_id": "string",
    "user_ip": "string",
    "user_agent": "string",
    "test_only": true
  },
  "store_context": {
    "location_code": "string"
  }
}'

Java

HttpResponse<String> response = Unirest.post("https://connect-ian.instacart.com/v2/ian/bp")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .header("X-Retailer-Id", "string")
  .body("{\n  \"slug\": \"string\",\n  \"page_view_id\": \"string\",\n  \"interaction_id\": \"string\",\n  \"session_context\": {\n    \"user_id\": \"string\",\n    \"user_ip\": \"string\",\n    \"user_agent\": \"string\",\n    \"test_only\": true\n  },\n  \"store_context\": {\n    \"location_code\": \"string\"\n  }\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect-ian.instacart.com")

payload = "{\n  \"slug\": \"string\",\n  \"page_view_id\": \"string\",\n  \"interaction_id\": \"string\",\n  \"session_context\": {\n    \"user_id\": \"string\",\n    \"user_ip\": \"string\",\n    \"user_agent\": \"string\",\n    \"test_only\": true\n  },\n  \"store_context\": {\n    \"location_code\": \"string\"\n  }\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>",
    'X-Retailer-Id': "string"
}

conn.request("POST", "/v2/ian/bp", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect-ian.instacart.com/v2/ian/bp"

	payload := strings.NewReader("{\n  \"slug\": \"string\",\n  \"page_view_id\": \"string\",\n  \"interaction_id\": \"string\",\n  \"session_context\": {\n    \"user_id\": \"string\",\n    \"user_ip\": \"string\",\n    \"user_agent\": \"string\",\n    \"test_only\": true\n  },\n  \"store_context\": {\n    \"location_code\": \"string\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Retailer-Id", "string")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
slug	string		The slug and unique name of the brand page.
desktop_image	ImageMediumProperties		Image hero banner of brand page used for desktop.
mobile_image	ImageMediumProperties		Image hero banner of brand page used for mobile.
logo_image	ImageMediumProperties		Logo of brand page.
ordered_versioned_block_ids	Array(BlockVersionedId)		Ordered list of block ids (not including the hero banner).
tracking_params	TrackingParams		Tracking params for brand page.

ImageMediumProperties Object

Field	Type	Required	Description
public_url	string		Public URL that a client must use for rendering. This URL uses the https:// scheme.
alt_text	string		Alternative text to display in case the image fails loading.
image_metadata	ImageMetadata		Additional information about the image. This can be used to assist rendering, where needed.

ImageMetadata Object

Field	Type	Required	Description
width	integer		Width of the image.
height	integer		Height of the image.
size_bytes	integer		Size of the image.
content_type	string		MIME-type of the image.

BlockVersionedId Object

Field	Type	Required	Description
type	string		Type of the brand page block. Supported values: ['PRODUCT_COLLECTION', 'SPOTLIGHT_PRODUCT_COLLECTION', 'SECTION_BANNER', 'IMAGE_STORY').
versioned_identifier	VersionedId		Versioned identifier of the block.

VersionedId Object

Field	Type	Required	Description
gid	string		Unique ID of the entity.
version	integer		Version of the entity.

TrackingParams Object

Field	Type	Required	Description
serving_id	string		Unique identifier to tag all events associated with a brand page instance.
brand_page_id	string		Unique identifier of the brand page.

Response examples

200 Success

200 Request with all attributes ok

{
  "slug": "ben-jerry",
  "desktop_image": {
    "public_url": "https://display.instacart.dev/cdn-cgi/image.png",
    "alt_text": "Awesome alt text!"
  },
  "mobile_image": {
    "public_url": "https://display.instacart.dev/cdn-cgi/image.png",
    "alt_text": "Awesome alt text!"
  },
  "logo_image": {
    "public_url": "https://display.instacart.dev/cdn-cgi/image.png",
    "alt_text": "Logo alt text!"
  },
  "ordered_versioned_block_ids": [
    {
      "type": "SPOTLIGHT_PRODUCT_COLLECTION",
      "versioned_identifier": {
        "gid": "9dd46839-2fd9-4e21-88cd-5af569b87421",
        "version": 1
      }
    },
    {
      "type": "SECTION_BANNER",
      "versioned_identifier": {
        "gid": "082be2d9-e1ca-4a39-a99d-ff166c46c154",
        "version": 1
      }
    },
    {
      "type": "PRODUCT_COLLECTION",
      "versioned_identifier": {
        "gid": "a1cd5b8e-4f07-4edb-9804-86861f9470ca",
        "version": 1
      }
    }
  ],
  "tracking_params": {
    "serving_id": "01965f4e-aa9c-732b-9474-d8f5060dd328",
    "brand_page_id": "14827667-c486-4bef-a3db-4b84bf9d5c67"
  }
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Missing slug	"can't be blank"	1001	{"key":"slug"}
400	Missing page view id	"can't be blank"	1001	{"key":"page_view_id"}
400	Invalid page view ID	"must be a UUID or 'None'"	1001	{"key":"page_view_id"}
400	too long user_id in the session context	"User ID length must be less than 51 characters"	1001	{"key":"session_context.user_id"}
400	too long location code in the store context	"Location code length must be less than 101 characters"	1001	{"key":"store_context.location_code"}