--- title: Display V3 slug: fluid-adserver-api/display-v3 docTags: createdAt: 2024-09-02T10:53:09.297Z --- { "id": "ZjahrZbdX2J1yfy9UKybY", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://localhost/v3/{publisherUUID}", "servers": [], "name": "Display 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
\n

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.\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": "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.

", "maxLength": 400 }, { "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": "

Additional information about the product, such as the price, availability, and other attributes.

", "example": "", "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": 400 }, { "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.

\n

Validation 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": [] } ] } ] } ], "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": "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": "targetUrl", "kind": "optional", "type": "string", "description": "The URL to which the user should be redirected when clicking on the ad.", "example": "https://www.example.com" }, { "name": "beaconUrls", "kind": "optional", "type": "array", "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)

", "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 display ad. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)

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

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "extTracking", "kind": "optional", "type": "", "description": "

Additional tracking URLs for the display ad. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)

", "example": "{\"OnFileClickBeacon\":[\"https://tracking/fileClick\"]}" }, { "name": "ext", "kind": "optional", "type": "object", "description": "

Additional information about the display ad. This attribute could be present when the sponsored = true for a specific position. (OPTIONAL)

", "example": "{\"key\":\"value\"}", "schema": [] }, { "name": "advertiserName", "kind": "optional", "type": "string", "description": "

The advertiser sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)

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

The advertiser ID sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)

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

The campaign name sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)

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

The campaign ID sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)

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

The ad group name sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)

", "example": "ad group X" }, { "name": "adGroupId", "kind": "optional", "type": "integer", "description": "

The ad group ID sponsoring this position. Only present for PMP display ads when configured as an exposed attribute for the publisher. (OPTIONAL)

", "example": 1 }, { "name": "demandSources", "kind": "optional", "type": "array", "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)

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

List of sponsored products associated with the display ad. optional

", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "gtin", "kind": "optional", "type": "string", "description": "" }, { "name": "beaconUrls", "kind": "optional", "type": "array", "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)

", "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 on this product of the display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "ext", "kind": "optional", "type": "object", "description": "

Additional information about this product of the display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)

", "example": "{\"key\":\"value\"}", "schema": [] } ] }, { "name": "banner", "kind": "optional", "type": "object", "description": "A set of different sizes of the same display ad.", "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\"}}}", "schema": [ { "name": "assetUrl", "kind": "optional", "type": "string", "description": "The URL of the asset to display.", "example": "https://www.example.com/image.jpg" }, { "name": "beaconUrls", "kind": "optional", "type": "array", "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)

", "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 display ad. This attribute would be present when the sponsored = true for a specific position. (OPTIONAL)

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

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

", "example": "{\"type\":\"IMAGE\",\"backgroundColor\":\"blue\",\"altText\":\"some_image5\",\"callToAction\":\"click here\"}", "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": "qXcvy8UVyb7-VnvbzBpER", "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": "wkZlMsOfnMpU55Mi9m9XM", "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": "X_lf_kqoMsu949goorh_f", "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": "-lTpisKD-DyF6MkF83oFf", "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": "qXcvy8UVyb7-VnvbzBpER" }, "results": { "languages": [ { "id": "zyRKJ2x3CE876LSXd4cWy", "language": "200", "code": "// OK\n{\n \"requestId\": \"\",\n \"adUnits\": [\n {\n \"adUnitId\": \"\",\n \"positions\": [\n {\n \"sponsored\": \"true | false\",\n \"kind\": \"\",\n \"targetUrl\": \"https://www.example.com\",\n \"beaconUrls\": [\n \"\"\n ],\n \"clickUrls\": [\n \"\"\n ],\n \"loadUrls\": [\n \"\"\n ],\n \"extTracking\": \"{\\\"OnFileClickBeacon\\\":[\\\"https://tracking/fileClick\\\"]}\",\n \"ext\": {},\n \"advertiserName\": \"advertiser X\",\n \"advertiserId\": 1,\n \"campaignName\": \"campaign X\",\n \"campaignId\": 1,\n \"adGroupName\": \"ad group X\",\n \"adGroupId\": 1,\n \"demandSources\": [\n \"\"\n ],\n \"associatedProducts\": [\n {\n \"gtin\": \"\",\n \"beaconUrls\": [\n \"\"\n ],\n \"clickUrls\": [\n \"\"\n ],\n \"ext\": {}\n }\n ],\n \"banner\": {\n \"assetUrl\": \"https://www.example.com/image.jpg\",\n \"beaconUrls\": [\n \"\"\n ],\n \"clickUrls\": [\n \"\"\n ],\n \"loadUrls\": [\n \"\"\n ],\n \"ext\": {}\n }\n }\n ]\n }\n ]\n}" }, { "id": "Feo1w_b5serqcMfXIOGqK", "language": "400", "code": "// One or more request parameters don't comply to the API specifications.\n{\n \"errors\": [\n \"\"\n ]\n}" }, { "id": "6w9JWT1WI3GVMnBnONboq", "language": "404", "code": "// One of the request ad unit IDs is unknown.\n{\n \"errors\": [\n \"\"\n ]\n}" } ], "selectedLanguageId": "zyRKJ2x3CE876LSXd4cWy" } }, "children": [ { "text": "" } ] }