Skip to main content

Get display placements

POST /v2/ian/dp

Retrieves display placements to display in banners on your site, such as display ads, shoppable display ads, and shoppable video ads. Specify the context in the request body.

Security​

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters​

NameInTypeRequiredDescription
X-Retailer-IdheaderstringOptionalThe retailer slug. This is only required for a retailer with multiple banners. Retailers with single banners can leave this empty.

Request​

FieldTypeRequiredDescription
page_contextDisplayPageContextRequiredSpecific page context for the requested ads.
placement_contextDisplayPlacementContextRequiredSpecific display placement context for the requested ads.
session_contextSessionContextRequiredContext related to the user session.
store_contextStoreContextRequiredContext related to the selected store.

DisplayPageContext Object​

FieldTypeRequiredDescription
page_queryDisplayQueryRequiredDefine one DisplayQuery object per request. This object sets the query for the page to show ads.
filter_queryFilterQueryOptionalA query used to filter the returned ads to only those that match the filter. The filter query is independent of the page type. Note: To use the FilterQuery object, your catalog inventory file must contain the product tags, category IDs, or brand IDs that you want to use as filters. For more information, see the Filters concept in this documentation.
ad_load_queryAdLoadQueryOptionalThe query used to specify the number of ads to return.

DisplayQuery Object​

FieldTypeRequiredDescription
search_querySearchQueryOptionalSpecify only one of the options described in this table. This option retrieves the search page.
storefront_queryStorefrontQueryOptionalSpecify only one of the options described in this table. This option retrieves the storefront page.
product_category_queryProductCategoryQueryOptionalSpecify only one of the options described in this table. This option retrieves the product category page.

SearchQuery Object​

FieldTypeRequiredDescription
page_view_idstringOptionalUnique identifier of a search page view. Must be a UUID (Universal Unique Identifier). Required for retailers. Optional for third-party partners.
search_termstringRequiredSearch query term.
enable_auto_correctbooleanOptionalApply-auto correction for the input search term. This option increases the latency of the endpoint. Defaults to true.

StorefrontQuery Object​

FieldTypeRequiredDescription
page_view_idstringOptionalUnique identifier of a retailer location storefront page view. Must be a UUID (Universal Unique Identifier). Required for retailers. Optional for third-party partners.

ProductCategoryQuery Object​

FieldTypeRequiredDescription
category_idsArray(integer)RequiredProduct category identifiers for the request.
page_view_idstringOptionalUnique identifier of a retailer product category page view. Must be a UUID (Universal Unique Identifier).

FilterQuery Object​

FieldTypeRequiredDescription
filter_tagsFilterTagsOptionalFilter tags that are used to filter the ads result. If a tag is included here, then sponsored products are included in the response only if the product has the corresponding tags. This filter is only applicable to shoppable display and shoppable video requests.
product_category_filter_queryProductCategoryFilterQueryOptionalThe query used to specify filters based off product_category_id's. It only applies to Search and BIA requests.
brand_idsArray(integer)OptionalAn array of brand IDs to use to filter the available ads. Ads are returned if they match any of the brand IDs. This filter is only applicable to shoppable display and shoppable video requests.

FilterTags Object​

FieldTypeRequiredDescription
tagsArray(string)RequiredArray list of tags or filter names as strings.

ProductCategoryFilterQuery Object​

FieldTypeRequiredDescription
category_idsArray(integer)RequiredProduct category identifiers for the request.

AdLoadQuery Object​

FieldTypeRequiredDescription
ads_countstringOptionalThe maximum number of ads to return. The actual number of returned ads depends on the ad inventory available.

DisplayPlacementContext Object​

FieldTypeRequiredDescription
placement_kindDisplayKindRequiredDefine one DisplayKind object per request. This object sets the kind of placement for showing ads.

DisplayKind Object​

FieldTypeRequiredDescription
display_placementDisplayPlacementOptionalSpecify only one of the options described in this table. This option serves shoppable display ads, which include shoppable video or shoppable display.

DisplayPlacement Object​

FieldTypeRequiredDescription
supported_formatArray(string)Requiredsupported formats: ['shoppable_display', 'shoppable_video', 'image_banner'].
rectangle_queryRectangleQueryRequiredThe query for the rectangular space that needs to be filled with a display ad.

RectangleQuery Object​

FieldTypeRequiredDescription
positionstringRequiredThe position of the rectangle space. This could be at the top or interleaved into middle of the page. Supported values: ['top', 'interleaved'].

SessionContext Object​

FieldTypeRequiredDescription
user_idstringRequiredUnique user ID of the user performing the query. Maximum 50 characters.
user_ipstringRequiredThe IP address of the end user. Maximum 50 characters.
user_agentstringRequiredThe user agent of the device making the request. Maximum 50 characters.
test_onlybooleanOptionalWhen 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​

FieldTypeRequiredDescription
location_codestringRequiredThe store location code used to perform the query. Maximum 100 characters.

Request examples​

curl --request POST \
  --url https://connect-ian.instacart.com/v2/ian/dp \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Retailer-Id: string' \
  --data '{
  "page_context": {
    "page_query": {
      "search_query": {
        "page_view_id": "string",
        "search_term": "string",
        "enable_auto_correct": true
      }
    },
    "filter_query": {
      "filter_tags": {
        "tags": [
          "string"
        ]
      }
    },
    "ad_load_query": {
      "ads_count": "string"
    }
  },
  "placement_context": {
    "placement_kind": {
      "display_placement": {
        "supported_format": [
          "string"
        ],
        "rectangle_query": {
          "position": "top"
        }
      }
    }
  },
  "session_context": {
    "user_id": "string",
    "user_ip": "string",
    "user_agent": "string",
    "test_only": true
  },
  "store_context": {
    "location_code": "string"
  }
}'

Response​

FieldTypeRequiredDescription
creativesArray(Creative)OptionalList of display creatives.

Creative Object​

FieldTypeRequiredDescription
object_tracking_idstringRequiredA unique tracking identifier for the creative instance in the auction where it ran.
typestringRequiredThe type of the creative. The type sets the expected identifiers and their respected types on the actions and assets.
assetsArray(Asset)OptionalList of assets associated with the creative.
actionsArray(Action)OptionalList of actions associated with the creative.
propertiesArray(CreativeProperty)OptionalList of properties associated with the creative.

Asset Object​

FieldTypeRequiredDescription
namestringOptionalThe name of the asset. Supported values: ['brand_logo', 'hero_image', 'image_web', 'image_mobile'].
typestringRequiredThe type of asset, which sets constraints over the asset medium's properties. Supported values: ['image_display_banner_large', 'image_display_banner_small', 'brand_logo_promoted_aisle', 'image_promoted_aisle_hero_banner'].
medium_propertiesPropertiesOptionalUsed to describe both the medium of the asset and the properties that are inherent to such a medium.

Properties Object​

FieldTypeRequiredDescription
imageImageMediumPropertiesOptionalProperties of the image medium.
videoVideoMediumPropertiesOptionalProperties of the video medium.

ImageMediumProperties Object​

FieldTypeRequiredDescription
public_urlstringRequiredPublic URL that a client must use for rendering. This URL uses the https:// scheme.
alt_textstringOptionalAlternative text to display in case the image fails loading.
image_metadataImageMetadataOptionalAdditional information about the image. This can be used to assist rendering, where needed.

ImageMetadata Object​

FieldTypeRequiredDescription
widthintegerOptionalWidth of the image.
heightintegerOptionalHeight of the image.
size_bytesintegerOptionalSize of the image.
content_typestringOptionalMIME-type of the image.

VideoMediumProperties Object​

FieldTypeRequiredDescription
video_urlstringRequiredPublic URL that a client must use for rendering.

Action Object​

FieldTypeRequiredDescription
namestringOptionalThe name of the action. Supported values: ['banner_click', 'main_product_group_grid_x'].
interaction_idstringRequiredUnique identifier of the action instance that should be used for tracking were this rendered in a client and interacted with.
action_propertiesActionPropertiesOptionalDescribes the action associated with the creative, such as render the brand page when the user clicks the banner.

ActionProperties Object​

FieldTypeRequiredDescription
brand_page_clickBrandPageClickOptionalClick to brand page action. One of the actions in this table is returned per action property.
item_cardItemCardOptionalThe action describes an item card. One of the actions in this table is returned per action property.

BrandPageClick Object​

FieldTypeRequiredDescription
slugstringRequiredIdentifier for a brand page. Example: '/pepsi/superbowl-page'.

ItemCard Object​

FieldTypeRequiredDescription
positionintegerRequiredThe suggested display position of the product.
product_idstringRequiredInstacart product ID.
rrcstringOptionalRetailer reference code (RRC) which can be used by retailers to fetch additional metadata about the product from their own catalog. One of RRC or UPC is returned depending on configurations by the retailer.
upcstringOptionalNon-normalized universal product code (UPC). One of RRC or UPC is returned depending on configurations by the retailer.

CreativeProperty Object​

FieldTypeRequiredDescription
namestringRequiredThe name of the property. Supported value: ['tagline'].
valuestringRequiredThe values of the property.

Response examples​

200 Success

{
  "creatives": [
    {
      "object_tracking_id": "urn:i-ic-v1:dcid:a/78219bd2-981d-49fb-a485-aaee5ddd8dfa",
      "type": "search_banner.v1",
      "assets": [
        {
          "type": "image_display_banner_large",
          "medium_properties": {
            "image": {
              "public_url": "https://cloudfront.net/image.jpg",
              "alt_text": "buy now",
              "image_metadata": {
                "width": 3200,
                "height": 400,
                "size_bytes": 123456,
                "content_type": "image/jpeg"
              }
            }
          }
        },
        {
          "type": "image_display_banner_small",
          "medium_properties": {
            "image": {
              "public_url": "https://cloudfront.net/image.jpg",
              "alt_text": "buy now",
              "image_metadata": {
                "width": 3200,
                "height": 400,
                "size_bytes": 123456,
                "content_type": "image/jpeg"
              }
            }
          }
        }
      ],
      "actions": [
        {
          "name": "banner_click",
          "interaction_id": "fc1f4b15-1c13-410f-bdc2-8457bbe95206",
          "action_properties": {
            "brand_page_click": {
              "slug": "/pepsi/superbowl-page"
            }
          }
        }
      ]
    }
  ]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400empty page query"the number of attributes given for page_query is 0"1001{"key":"page_context.page_query"}
400Request with more than one attribute used in page query"the number of attributes given for page_query is 2"1001{"key":"page_context.page_query"}
400empty placement kind"the number of attributes given for placement_kind is 0"1001{"key":"placement_context.placement_kind"}
400invalid placement kind"the number of attributes given for placement_kind is 0"1001{"key":"placement_context.placement_kind"}
400too long user_id in the session context"User ID length must be less than 51 characters"1001{"key":"session_context.user_id"}
400too long location code in the store context"Location code length must be less than 101 characters"1001{"key":"store_context.location_code"}
401store that doesn't match the oauth token used"the given location code doesn't match the oauth token used."nullNot applicable
Last updated on