Display V3

POST

https://localhost/v3/{publisherUUID}

This endpoint expects an adRequest with at least one of the following inventory inputs:

products
additionalProducts
categories

Based on the parameters in the AdRequest, inventory inputs, and the configs of the AdUnits the placement algorithm decides how to reorder the creatives, and how to place the display banners in the AdResponse. The AdRequest allows also to send multiple adUnits in the same requests, and in this case the placement algorithm makes sure it does the deduplication of ads between the AdUnits.

Path Parameters

publisherUUIDstringrequired
Description
The UUID of a publisher, this value is provided by Pentaleap during the integration process

Body Parameters

bodyRequestrequired
- userUserrequired
  - idstring
    Description
    Unique identifier for the end user, used for attributing the user's purchases/conversions. It's recommended to have this value as fixed and consistent across publisher sites and client devices for more accurate attribution reports. (Note: Either id or loggedInId is required)
    Min Length
    1
    Max Length
    128
  - loggedInIdstring
    Description
    [Optional] A persistent user ID for logged in users/customers
    Min Length
    1
    Max Length
    128
  - additionalIdsmap<string, string>
    Example
    { "partner_x_id": "id123", "partner_y_id": "id456" }
    Description
    [Optional] optional publisher-provided IDs for reporting and analytics purposes
    
    Validation Rules:
    
    maxProperties: 20 Each value:
    
    minLength: 1
    
    maxLength: 128
  - ipstring
    Description
    The IP address of the end user. This value is never stored, however, it can be helpful for debugging, and monitoring.
    Max Length
    60
  - agentstring
    Example
    Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36
    Description
    The user agent of the client application the end user used.
    Max Length
    400
  - regionstring
    Example
    *066
    Description
    The region of the end user, used to apply product regional availability logic. It prevents products from being sponsored in regions where they are out of stock. The value of this field has to match with values provided through the regional availability feed integration point.
    Max Length
    100
  - segmentsstring[]
    Example
    [ "income_>10k", "gender_male" ]
    Description
    Specifies to which segments the user belongs, used for reporting on the level of segment and for bid modifiers Validation Rules:
    
    maxItems: 100
    
    items:
    
    type: string
    
    maxLength: 60
  - limitedTrackingboolean
    Description
    Specifies whether the user has chosen to limit tracking.
- adUnitsAdUnit[]required
  Description
  specifies ad unit requests parameters.
  
  Validation Rules:
  
  minItems: 1
  
  maxItems: 6
  - adUnitIdstringrequired
    Description
    The UUID of a publisher's ad unit. This value is provided by Pentaleap.
    Min Length
    1
    Max Length
    100
  - searchQuerystring
    Description
    The search query that the user entered for the current adRequest, this is valid for the search pages only.
    Max Length
    400
  - productsobject[]
    Description
    Contains the retailer's organic products.
    
    Validation Rules:
    
    maxItems: 200
    - gtingtin
      Description
      Is typically the "Global Trade Item Number" but generally
      a retailer's unique product identifier.
      
      Validation Rules:
      
      maxLength: 60
    - ignoreBidboolean
      Description
      When true, the ad placement algorithm doesn't consider this product for sponsoring, and this only applies to SPA (Sponsored Product Ads).
      Default
      false
    - pinnedboolean
      Description
      When true, the ad placement algorithm doesn't move this product from its organic positions; this only applies to SPA (Sponsored Product Ads).
      Default
      false
    - extobject
      Description
      Additional information about the product, such as the price, availability, and other attributes.
  - categoriesobject
    Description
    List of categories which their associated products are considered in the ad placement algorithm. The categories should match the categories provided in the feed, otherwise they will be ignored
    - currentstring
      Description
      The category of the page the user is currently viewing. Applies mainly for category pages.
      Max Length
      400
    - additionalstring[]
      Description
      List of additional categories that should be considered by the placement algorithm, for example to extend the inventory.
      
      Validation Rules:
      
      maxItems: 20
      
      items:
      
      type: string
      
      maxLength: 400
  - additionalProductsobject[]
    Description
    Extended list of products that can be utilised to increase the available candidates list which can be used in the sponsoring algorithm.
    
    Validation Rules:
    
    maxItems: 200
    - gtingtin
      Description
      Is typically the "Global Trade Item Number" but generally
      a retailer's unique product identifier.
      
      Validation Rules:
      
      maxLength: 60

Responses

200OK

AdResponse
- requestIdstring
- adUnitsobject[]
  - adUnitIdstring
  - positionsobject[]
    - sponsoredboolean
      Example
      true | false
    - kindstring
      Description
      The value of the attribute can be Fluid, Injected, Not Sponsored as per the algorithm which would be running as per the position type
    - targetUrlstring
      Example
      https://www.example.com
      Description
      The URL to which the user should be redirected when clicking on the ad.
    - beaconUrlsstring[]
      Description
      an array of beacon URLs to be triggered whenever the user "sees" this display ad. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)
    - clickUrlsstring[]
      Description
      an array of click URLs to be triggered whenever the user clicks this display ad. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)
    - loadUrlsstring[]
      Description
      an array of load URLs to be triggered whenever this display ad is loaded in a the page that the user is visiting. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)
    - extTracking
      Example
      { "OnFileClickBeacon": [ "https://tracking/fileClick" ] }
      Description
      Additional tracking URLs for the display ad. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)
    - extobject
      Example
      { "key": "value" }
      Description
      Additional information about the display ad. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)
    - advertiserNamestring
      Example
      advertiser X
      Description
      The advertiser sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)
    - advertiserIdinteger
      Example
      1
      Description
      The advertiser ID sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)
    - campaignNamestring
      Example
      campaign X
      Description
      The campaign name sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)
    - campaignIdinteger
      Example
      1
      Description
      The campaign ID sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)
    - adGroupNamestring
      Example
      ad group X
      Description
      The ad group name sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)
    - adGroupIdinteger
      Example
      1
      Description
      The ad group ID sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)
    - demandSourcesstring[]
      Example
      [ "pentaleap" ]
      Description
      The demand source that won this position: ["pentaleap"] for PMP display ads, or the name of the external DSP for DSP display ads, e.g. ["dsp X"]. Present for both PMP and DSP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)
    - associatedProductsobject[]
      Description
      List of sponsored products associated with the display ad. optional
      - gtinstring
      - beaconUrlsstring[]
        Description
        an array of beacon URLs to be triggered whenever the user "sees" this product of the display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)
      - clickUrlsstring[]
        Description
        an array of click URLs to be triggered whenever the user clicks on this product of the display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)
      - extobject
        Example
        { "key": "value" }
        Description
        Additional information about this product of the display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)
    - bannerobject
      Example
      { "300x250": { "assetUrl": "https://www.example.com/image_300x250.jpg", "beaconUrls": [ "https://www.example.com/tracking/impression/image_300x250" ], "clickUrls": [ "https://www.example.com/tracking/click/image_300x250" ] }, "728x90": { "assetUrl": "https://www.example.com/image_728x90.jpg", "beaconUrls": [ "https://www.example.com/tracking/impression/image_728x90" ], "clickUrls": [ "https://www.example.com/tracking/click/image_728x90" ], "ext": { "type": "IMAGE", "backgroundColor": "blue", "altText": "some_image5", "callToAction": "click here" } } }
      Description
      A set of different sizes of the same display ad.
      - assetUrlstring
        Example
        https://www.example.com/image.jpg
        Description
        The URL of the asset to display.
      - beaconUrlsstring[]
        Description
        an array of beacon URLs to be triggered whenever the user "sees" this display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)
      - clickUrlsstring[]
        Description
        an array of click URLs to be triggered whenever the user clicks this display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)
      - loadUrlsstring[]
        Description
        an array of load URLs to be triggered whenever this display ad is loaded in a the page that the user is visiting. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)
      - extobject
        Example
        { "type": "IMAGE", "backgroundColor": "blue", "altText": "some_image5", "callToAction": "click here" }
        Description
        Additional information about the display ad, such as type, background color, alt text, and call to action. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)

400One or more request parameters don't comply to the API specifications.

ErrorResponse
- errorsstring[]

404One of the request ad unit IDs is unknown.

ErrorResponse
- errorsstring[]

curl

curl --request POST \
     --url https://localhost/v3/{publisherUUID} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "user": {},
     "adUnits": [
     {
     "adUnitId": ""
     }
     ]
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "user": {},
   "adUnits": [
      {
         "adUnitId": ""
      }
   ]
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://localhost/v3/{publisherUUID}", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://localhost/v3/{publisherUUID}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "user": {},
   "adUnits": [
      {
         "adUnitId": ""
      }
   ]
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://localhost/v3/{publisherUUID}"

payload = json.dumps({
   "user": {},
   "adUnits": [
      {
         "adUnitId": ""
      }
   ]
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// OK
{
  "requestId": "",
  "adUnits": [
    {
      "adUnitId": "",
      "positions": [
        {
          "sponsored": "true | false",
          "kind": "",
          "targetUrl": "https://www.example.com",
          "beaconUrls": [
            ""
          ],
          "clickUrls": [
            ""
          ],
          "loadUrls": [
            ""
          ],
          "extTracking": "{\"OnFileClickBeacon\":[\"https://tracking/fileClick\"]}",
          "ext": {},
          "advertiserName": "advertiser X",
          "advertiserId": 1,
          "campaignName": "campaign X",
          "campaignId": 1,
          "adGroupName": "ad group X",
          "adGroupId": 1,
          "demandSources": [
            ""
          ],
          "associatedProducts": [
            {
              "gtin": "",
              "beaconUrls": [
                ""
              ],
              "clickUrls": [
                ""
              ],
              "ext": {}
            }
          ],
          "banner": {
            "assetUrl": "https://www.example.com/image.jpg",
            "beaconUrls": [
              ""
            ],
            "clickUrls": [
              ""
            ],
            "loadUrls": [
              ""
            ],
            "ext": {}
          }
        }
      ]
    }
  ]
}

400

// One or more request parameters don't comply to the API specifications.
{
  "errors": [
    ""
  ]
}

404

// One of the request ad unit IDs is unknown.
{
  "errors": [
    ""
  ]
}