--- title: SPA V3 slug: fluid-adserver-api/spa-v3 docTags: createdAt: 2024-06-14T15:23:28.835Z --- { "id": "AzMFt7I6GWMlTbVpuQP0y", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://localhost/v3/{publisherUUID}", "servers": [], "name": "SPA V3", "description": "

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

\n
    \n
  1. products
    2. \n
  2. additionalProducts
    3. \n
  3. categories
    4. \n
  4. demandSources
    5. \n
\n

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.\nThe 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.

", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "publisherUUID", "type": "string", "description": "

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

" } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "", "customType": "Request", "schema": [ { "name": "user", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/User", "customType": "User", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "

Unique identifier for the end user, used for attributing the user's purchases/conversions.\nIt'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)

", "minLength": 1, "maxLength": 128 }, { "name": "loggedInId", "kind": "optional", "type": "string", "description": "

[Optional] A persistent user ID for logged in users/customers

", "minLength": 1, "maxLength": 128 }, { "name": "additionalIds", "kind": "optional", "type": "map", "description": "

[Optional] optional publisher-provided IDs for reporting and analytics purposes

\n

Validation Rules:

\n", "example": "{\"partner_x_id\":\"id123\",\"partner_y_id\":\"id456\"}", "customType": "map", "schema": [] }, { "name": "ip", "kind": "optional", "type": "string", "description": "

'The IP address of the end user. This value is never stored, however, it can be helpful for debugging, and monitoring.'

", "maxLength": 60 }, { "name": "agent", "kind": "optional", "type": "string", "description": "The user agent of the client application the end user used.\n", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36", "maxLength": 400 }, { "name": "region", "kind": "optional", "type": "string", "description": "

The region of the end user, used to apply product regional availability logic.\nIt prevents products from being sponsored in regions where they are out of stock.\nThe value of this field has to match with values provided through the regional availability feed integration point.

", "example": "*066", "maxLength": 100 }, { "name": "segments", "kind": "optional", "type": "array", "description": "

'Specifies to which segments the user belongs, used for reporting on the level of segment and for bid modifiers'\nValidation Rules:

\n", "example": "[\"income_>10k\",\"gender_male\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "limitedTracking", "kind": "optional", "type": "boolean", "description": "Specifies whether the user has chosen to limit tracking." } ] }, { "name": "adUnitContext", "kind": "optional", "type": "object", "description": "Common context for all ad units in the request. ad unit specific attributes override these values.", "example": "", "schema": [ { "name": "searchQuery", "kind": "optional", "type": "string", "description": "

'The search query that the user entered for the current adRequest, this is valid for the search pages only.'

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/searchQuery", "customType": "searchQuery", "schema": [] }, { "name": "products", "kind": "optional", "type": "array", "description": "

Contains the retailer's organic products.

\n

Validation Rules:

\n", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "gtin", "kind": "optional", "type": "string", "description": "

Is typically the \"Global Trade Item Number\" but generally\na retailer's unique product identifier.

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/gtin", "customType": "gtin", "schema": [] }, { "name": "ignoreBid", "kind": "optional", "type": "boolean", "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 }, { "name": "pinned", "kind": "optional", "type": "boolean", "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 }, { "name": "ext", "kind": "optional", "type": "object", "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).

", "example": "{\"attr1\":\"val1\",\"attr2\":\"val2\"}", "modelRef": "#/components/schemas/Ext", "customType": "Ext", "schema": [] } ] }, { "name": "additionalProducts", "kind": "optional", "type": "array", "description": "

Extended list of products that can be utilised to increase the available candidates list which can be used in the sponsoring algorithm.

\n

Validation Rules:

\n", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "gtin", "kind": "optional", "type": "string", "description": "

Is typically the \"Global Trade Item Number\" but generally\na retailer's unique product identifier.

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/gtin", "customType": "gtin", "schema": [] } ] }, { "name": "excludedProducts", "kind": "optional", "type": "array", "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).

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/excludedProducts", "customType": "excludedProducts", "schema": [] }, { "name": "demandSources", "kind": "optional", "type": "object", "description": "Mapping of external retailer's demand sources and their associated targets and bid sources.", "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\"]}}}}", "modelRef": "#/components/schemas/demandSources", "customType": "demandSources", "schema": [ { "name": "spa", "kind": "optional", "type": "map", "description": "

Demand source configurations for Sponsored Product Ads.\nValidation Rules:

\n", "example": "", "customType": "map", "schema": [] } ] } ] }, { "name": "adUnits", "kind": "required", "type": "array", "description": "

specifies ad unit requests parameters.

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/AdUnit", "customType": "AdUnit[]", "schema": [ { "name": "adUnitId", "kind": "required", "type": "string", "description": "The UUID of a publisher's ad unit. This value is provided by Pentaleap.\n", "minLength": 1, "maxLength": 100 }, { "name": "searchQuery", "kind": "optional", "type": "string", "description": "

'The search query that the user entered for the current adRequest, this is valid for the search pages only.'

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/searchQuery", "customType": "searchQuery", "schema": [] }, { "name": "products", "kind": "optional", "type": "array", "description": "

Contains the retailer's organic products.

\n

Validation Rules:

\n", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "gtin", "kind": "optional", "type": "string", "description": "

Is typically the \"Global Trade Item Number\" but generally\na retailer's unique product identifier.

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/gtin", "customType": "gtin", "schema": [] }, { "name": "ignoreBid", "kind": "optional", "type": "boolean", "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 }, { "name": "pinned", "kind": "optional", "type": "boolean", "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 }, { "name": "ext", "kind": "optional", "type": "object", "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).

", "example": "{\"attr1\":\"val1\",\"attr2\":\"val2\"}", "modelRef": "#/components/schemas/Ext", "customType": "Ext", "schema": [] } ] }, { "name": "categories", "kind": "optional", "type": "object", "description": "

List of categories which their associated products are considered in the ad placement algorithm.\nThe categories should match the categories provided in the feed, otherwise they will be ignored

", "example": "", "schema": [ { "name": "current", "kind": "optional", "type": "string", "description": "The category of the page the user is currently viewing. Applies mainly for category pages.\n", "maxLength": 200 }, { "name": "additional", "kind": "optional", "type": "array", "description": "

'List of additional categories that should be considered by the placement algorithm, for example to extend the inventory.'\nValidation Rules:

\n", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] }, { "name": "additionalProducts", "kind": "optional", "type": "array", "description": "

Extended list of products that can be utilised to increase the available candidates list which can be used in the sponsoring algorithm.

\n

Validation Rules:

\n", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "gtin", "kind": "optional", "type": "string", "description": "

Is typically the \"Global Trade Item Number\" but generally\na retailer's unique product identifier.

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/gtin", "customType": "gtin", "schema": [] } ] }, { "name": "excludedProducts", "kind": "optional", "type": "array", "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).

\n

Validation Rules:

\n", "modelRef": "#/components/schemas/excludedProducts", "customType": "excludedProducts", "schema": [] }, { "name": "demandSources", "kind": "optional", "type": "object", "description": "Mapping of external retailer's demand sources and their associated targets and bid sources.", "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\"]}}}}", "modelRef": "#/components/schemas/demandSources", "customType": "demandSources", "schema": [ { "name": "spa", "kind": "optional", "type": "map", "description": "

Demand source configurations for Sponsored Product Ads.\nValidation Rules:

\n", "example": "", "customType": "map", "schema": [] } ] }, { "name": "onlySponsored", "kind": "optional", "type": "boolean", "description": "A flag that controls whether to return only sponsored positions in the response.", "default": false }, { "name": "excludePositionKind", "kind": "optional", "type": "array", "description": "

List of position kinds to be excluded from the ad placement results. Possible values are:

\n
    \n
  • Injected - exclude injected positions from the ad placement results
    • \n
  • Fluid - exclude fluid positions from the ad placement results
    • \n
  • Display - exclude display positions from the ad placement results
    • \n
", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ], "modelRef": "#/components/schemas/Request", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "OK", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "AdResponse", "schema": [ { "name": "requestId", "kind": "optional", "type": "string", "description": "" }, { "name": "adUnits", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "adUnitId", "kind": "optional", "type": "string", "description": "" }, { "name": "positions", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "gtin", "kind": "optional", "type": "string", "description": "" }, { "name": "ext", "kind": "optional", "type": "object", "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).

", "example": "{\"attr1\":\"val1\",\"attr2\":\"val2\"}", "modelRef": "#/components/schemas/Ext", "customType": "Ext", "schema": [] }, { "name": "beaconUrls", "kind": "optional", "type": "array", "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.

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "clickUrls", "kind": "optional", "type": "array", "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.

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "loadUrls", "kind": "optional", "type": "array", "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)

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "sponsored", "kind": "optional", "type": "boolean", "description": "", "example": "true | false" }, { "name": "kind", "kind": "optional", "type": "string", "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

" }, { "name": "brand", "kind": "optional", "type": "string", "description": "

The brand sponsoring this position (OPTIONAL)

", "example": "brand X" }, { "name": "advertiserName", "kind": "optional", "type": "string", "description": "

The advertiser sponsoring this position (OPTIONAL)

", "example": "advertiser X" }, { "name": "advertiserId", "kind": "optional", "type": "number", "description": "

The advertiser ID sponsoring this position (OPTIONAL)

", "example": 1 }, { "name": "campaignName", "kind": "optional", "type": "string", "description": "

The campaign name sponsoring this position (OPTIONAL)

", "example": "campaign X" }, { "name": "campaignId", "kind": "optional", "type": "number", "description": "

The campaign ID sponsoring this position (OPTIONAL)

", "example": 1 }, { "name": "adGroupId", "kind": "optional", "type": "number", "description": "

The ad group ID sponsoring this position (OPTIONAL)

", "example": 1 }, { "name": "adGroupName", "kind": "optional", "type": "string", "description": "

The ad group name sponsoring this position (OPTIONAL)

", "example": "ad group X" }, { "name": "productGroupId", "kind": "optional", "type": "number", "description": "

The product group ID of the product sponsoring this position (OPTIONAL)

", "example": 1 }, { "name": "productTitle", "kind": "optional", "type": "string", "description": "

The product title of the product sponsoring this position (OPTIONAL)

", "example": "product title X" }, { "name": "productCategories", "kind": "optional", "type": "array", "description": "

The product categories of the product sponsoring this position (OPTIONAL)

", "example": "[\"category X\",\"category Y\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "demandSources", "kind": "optional", "type": "array", "description": "

The demand sources for the product sponsoring this position (OPTIONAL)

", "example": "[\"source X\",\"source Y\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] }, { "name": "ext", "kind": "optional", "type": "map", "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).

", "example": "{\"dspName\":[{\"key1\":\"value1\"},{\"key2\":\"value2\"}]}", "customType": "map", "schema": [] } ] } ], "modelRef": "#/components/schemas/AdResponse", "isExpanded": true } ] }, { "statusCode": "400", "description": "One or more request parameters don't comply to the API specifications.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "errors", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "404", "description": "One of the request ad unit IDs is unknown.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "errors", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "mkYFHoajEw4FdlO452m_q", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://localhost/v3/{publisherUUID} \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n }'" }, { "id": "2WLIzT0nVkS0XS9sFxCrt", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://localhost/v3/{publisherUUID}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "Q_4FW_lvObslvRl9ygk8C", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://localhost/v3/{publisherUUID}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "LgDrRVb5beldyxCH21hyy", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://localhost/v3/{publisherUUID}\"\n\npayload = json.dumps({\n \"user\": {},\n \"adUnits\": [\n {\n \"adUnitId\": \"\"\n }\n ]\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "mkYFHoajEw4FdlO452m_q" }, "results": { "languages": [ { "id": "nsekvxOhoqDeEppPmirCl", "language": "200", "code": "// OK\n{\n \"requestId\": \"\",\n \"adUnits\": [\n {\n \"adUnitId\": \"\",\n \"positions\": [\n {\n \"gtin\": \"\",\n \"ext\": {},\n \"beaconUrls\": [\n \"\"\n ],\n \"clickUrls\": [\n \"\"\n ],\n \"loadUrls\": [\n \"\"\n ],\n \"sponsored\": \"true | false\",\n \"kind\": \"\",\n \"brand\": \"brand X\",\n \"advertiserName\": \"advertiser X\",\n \"advertiserId\": 1,\n \"campaignName\": \"campaign X\",\n \"campaignId\": 1,\n \"adGroupId\": 1,\n \"adGroupName\": \"ad group X\",\n \"productGroupId\": 1,\n \"productTitle\": \"product title X\",\n \"productCategories\": [\n \"\"\n ],\n \"demandSources\": [\n \"\"\n ]\n }\n ],\n \"ext\": \"{\\\"dspName\\\":[{\\\"key1\\\":\\\"value1\\\"},{\\\"key2\\\":\\\"value2\\\"}]}\"\n }\n ]\n}" }, { "id": "H18f3laY2SdZOVuqn2oDH", "language": "400", "code": "// One or more request parameters don't comply to the API specifications.\n{\n \"errors\": [\n \"\"\n ]\n}" }, { "id": "9pvlwClF6sdu3CfM1KDqg", "language": "404", "code": "// One of the request ad unit IDs is unknown.\n{\n \"errors\": [\n \"\"\n ]\n}" } ], "selectedLanguageId": "nsekvxOhoqDeEppPmirCl" } }, "children": [ { "text": "" } ] }