Request and Response Overview

Ad Request/Response Protocol

The main Pentaleap call is to an adserver-like API is used to request and receive ads from connected demand sources.

Ad unit IDs are provided to you from your own Publisher Manager UI. Page context is passed by sharing information such as organic products, search queries and categories as relevant; you may also specify additional products and categories to be in scope for sponsorship.

Sponsored Products and Display/Sponsored Brand ads follow a common request format (and we recommend that they are called together in one request), but have different responses (Display and SPonsored Brand ads have additional assets, associated products etc). Please see SPA V3 and Display V3Display V3 for the exact API Specifications.

Multiple Ad Units can be called in a single request, and Sponsored Product and Display/Sponsored Brand-type units are also called in the same request format.

For full specification, please check out the API specifications with examples for Sponsored Products and Display Ads in the respective sections.

IMPORTANT:

Please check out the Adserver FAQ section to understand some common behaviours and rules of the ad response.

Please see Integration Best PracticesIntegration Best Practices for advice on calling the APIs generally

If your use case includes accessing real-time third party demand, please also see the Warmup API documentation

For specific use cases and recommendations, please see theUse Cases and Best Practise use cases section

Here is a sample ad request structure - the response includes both Sponsored Product and Display ads in BATCHED call - i.e. you can call multiple ad units at once, and those ad units can be both SPA and Display/Sponsored Brand ads:

{
    "user": {
        "id": "TEST"
    },
    "adUnitContext": { //Page Context goes into adUnitContext - it's shared by all ad units
        "searchQuery": "shampoo",
        "products": [ //ordered list of GTINs/SKUs organically on the page - max 200 (can contain multiple UI pages)
                {
                    "gtin": "ABC"
                },
                {
                    "gtin": "123"
                },
                {
                    "gtin": "DEF123"
                },
                {
                    "gtin": "345"
                },
                {
                    "gtin": "123"
                },
                {
                    "gtin": "..."
                },
                {
                    "gtin": "XYZ"
                }
      ]
    },
    "adUnits": [ //max. 6 per request
        {
            "adUnitId": "[SPA Ad Unit ID 1]"//Search Main Grid
        },
        {
            "adUnitId" : "[Display Ad Unit ID 1]" //Display Above the Fold Search

        }
    ]
}

The response returns sponsored and in some cases organic content to be rendered, plus additional information required for rendering and reporting.

Sample response:

{
  "adUnits": [
    {
      "adUnitId": "[SPA Ad Unit ID 1]", //returns SPA ad unit information + organic information
      "positions": [
        {
          "gtin": "string",
          "sponsored": false,
          "kind": "string",
          "ext": {
            "attr1": "val1",
            "attr2": "val2"
          }
        },
        {
          "gtin": "string",
          "sponsored": true,
          "kind": "string",
          "beaconUrls": [
            "string"
          ],
          "clickUrls": [
            "string"
          ],
          "ext": {
            "attr1": "val1",
            "attr2": "val2"
          }
        },
        {
            "adUnitId": "[Display Ad Unit ID 1]", //returns Display ad unit information
            "positions": [
                {
                    "banner": {
                        "300x250": {
                            "assetUrl": "linktoasset.com",
                            "clickUrls": [
                                "https://trackerUrl"
                            ],
                            "beaconUrls": [
                                "https://trackerUrl"
                            ],
                            "ext": {
                                "type": "IMAGE"
                            }
                        },
                        "970x250": {
                            "assetUrl": "linktoasset.com",
                            "clickUrls": [
                                "https://trackerUrl"
                            ],
                            "beaconUrls": [
                                "https://trackerUrl"
                            ],
                            "ext": {
                                "type": "IMAGE",
                                "adCopy": "This is an ad copy"
                            }
                        },
                        "dynamic": {
                            "assetUrl": "linktoasset.com",
                            "clickUrls": [
                                "https://trackerUrl"
                            ],
                            "beaconUrls": [
                                "https://trackerUrl"
                            ],
                            "ext": { //Contains additional ad information for rendering display ad
                                "type": "HTML_IMAGE_LINK"
                            }
                        }
                    },
                    "kind": "Display",
                    "targetUrl": "https://pentaleap.com",
                    "sponsored": true
                }
            ]
        }
    ]
}