SPA V3

POST

https://localhost/v3/{publisherUUID}

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

products
additionalProducts
categories
demandSources

Based on the parameters in the AdRequest, inventory inputs, and the configs of the AdUnits the placement algorithm decides how to reorder the products, and how to place the ads 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.
- adUnitContextobject
  Description
  Common context for all ad units in the request. ad unit specific attributes override these values.
  - searchQuerysearchQuery
    Description
    'The search query that the user entered for the current adRequest, this is valid for the search pages only.'
    
    Validation Rules:
    
    maxLength: 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
    - extExt
      Example
      { "attr1": "val1", "attr2": "val2" }
      Description
      Represents extra fields that we receive in the adRequest and return them as is in the adResponse. We do not have any restrictions about the keys and values except that the length of each does not exceed 200 characters. If the same key appears twice, we return only the one with the last value, and this only applies to SPA (Sponsored Product Ads).
  - 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
  - excludedProductsexcludedProducts
    Description
    List of product GTINs that the ad placement algorithm excludes from sponsoring. Excluded products can still appear as organic positions but won't win sponsored placements. This only applies to SPA (Sponsored Product Ads).
    
    Validation Rules:
    
    maxItems: 200
  - demandSourcesdemandSources
    Example
    { "spa": { "demand_source_1": { "947081": { "bid": 2.3, "beaconUrls": [ "https://demand_source_1.com/tracking/impression/947081" ], "clickUrls": [ "https://demand_source_1.com/tracking/click/947081" ] } } } }
    Description
    Mapping of external retailer's demand sources and their associated targets and bid sources.
    - spamap<string, object>
      Description
      Demand source configurations for Sponsored Product Ads. Validation Rules:
      
      maxProperties: 5
- 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
  - searchQuerysearchQuery
    Description
    'The search query that the user entered for the current adRequest, this is valid for the search pages only.'
    
    Validation Rules:
    
    maxLength: 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
    - extExt
      Example
      { "attr1": "val1", "attr2": "val2" }
      Description
      Represents extra fields that we receive in the adRequest and return them as is in the adResponse. We do not have any restrictions about the keys and values except that the length of each does not exceed 200 characters. If the same key appears twice, we return only the one with the last value, and this only applies to SPA (Sponsored Product Ads).
  - 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
  - excludedProductsexcludedProducts
    Description
    List of product GTINs that the ad placement algorithm excludes from sponsoring. Excluded products can still appear as organic positions but won't win sponsored placements. This only applies to SPA (Sponsored Product Ads).
    
    Validation Rules:
    
    maxItems: 200
  - demandSourcesdemandSources
    Example
    { "spa": { "demand_source_1": { "947081": { "bid": 2.3, "beaconUrls": [ "https://demand_source_1.com/tracking/impression/947081" ], "clickUrls": [ "https://demand_source_1.com/tracking/click/947081" ] } } } }
    Description
    Mapping of external retailer's demand sources and their associated targets and bid sources.
    - spamap<string, object>
      Description
      Demand source configurations for Sponsored Product Ads. Validation Rules:
      
      maxProperties: 5
  - onlySponsoredboolean
    Description
    A flag that controls whether to return only sponsored positions in the response.
    Default
    false
  - excludePositionKindstring[]
    Description
    List of position kinds to be excluded from the ad placement results. Possible values are:
    
    Injected - exclude injected positions from the ad placement results
    
    Fluid - exclude fluid positions from the ad placement results
    
    Display - exclude display positions from the ad placement results

Responses

200OK

AdResponse
- requestIdstring
- adUnitsobject[]
  - adUnitIdstring
  - positionsobject[]
    - gtinstring
    - extExt
      Example
      { "attr1": "val1", "attr2": "val2" }
      Description
      Represents extra fields that we receive in the adRequest and return them as is in the adResponse. We do not have any restrictions about the keys and values except that the length of each does not exceed 200 characters. If the same key appears twice, we return only the one with the last value, and this only applies to SPA (Sponsored Product Ads).
    - beaconUrlsstring[]
      Description
      an array of beacon URLs to be triggered whenever the user "views" this sponsored product. This attribute would be present when the sponsored = true for a specific position.
    - clickUrlsstring[]
      Description
      an array of click URLs to be triggered whenever the user clicks this sponsored product. This attribute would be present when the sponsored = true for a specific position.
    - loadUrlsstring[]
      Description
      an array of load URLs to be triggered whenever an ad is loaded in the page the user is visting. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)
    - 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
    - brandstring
      Example
      brand X
      Description
      The brand sponsoring this position (OPTIONAL)
    - advertiserNamestring
      Example
      advertiser X
      Description
      The advertiser sponsoring this position (OPTIONAL)
    - advertiserIdnumber
      Example
      1
      Description
      The advertiser ID sponsoring this position (OPTIONAL)
    - campaignNamestring
      Example
      campaign X
      Description
      The campaign name sponsoring this position (OPTIONAL)
    - campaignIdnumber
      Example
      1
      Description
      The campaign ID sponsoring this position (OPTIONAL)
    - adGroupIdnumber
      Example
      1
      Description
      The ad group ID sponsoring this position (OPTIONAL)
    - adGroupNamestring
      Example
      ad group X
      Description
      The ad group name sponsoring this position (OPTIONAL)
    - productGroupIdnumber
      Example
      1
      Description
      The product group ID of the product sponsoring this position (OPTIONAL)
    - productTitlestring
      Example
      product title X
      Description
      The product title of the product sponsoring this position (OPTIONAL)
    - productCategoriesstring[]
      Example
      [ "category X", "category Y" ]
      Description
      The product categories of the product sponsoring this position (OPTIONAL)
    - demandSourcesstring[]
      Example
      [ "source X", "source Y" ]
      Description
      The demand sources for the product sponsoring this position (OPTIONAL)
  - extmap<string, object[]>
    Example
    { "dspName": [ { "key1": "value1" }, { "key2": "value2" } ] }
    Description
    Represents extra fields that we receive from External DSPs and return them as is in the adResponse at the ad unit level. If the same key appears twice, we return only the one with the last value. Currently this only applies to SPA (Sponsored Product Ads).

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": [
        {
          "gtin": "",
          "ext": {},
          "beaconUrls": [
            ""
          ],
          "clickUrls": [
            ""
          ],
          "loadUrls": [
            ""
          ],
          "sponsored": "true | false",
          "kind": "",
          "brand": "brand X",
          "advertiserName": "advertiser X",
          "advertiserId": 1,
          "campaignName": "campaign X",
          "campaignId": 1,
          "adGroupId": 1,
          "adGroupName": "ad group X",
          "productGroupId": 1,
          "productTitle": "product title X",
          "productCategories": [
            ""
          ],
          "demandSources": [
            ""
          ]
        }
      ],
      "ext": "{\"dspName\":[{\"key1\":\"value1\"},{\"key2\":\"value2\"}]}"
    }
  ]
}

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": [
    ""
  ]
}