Placement API

The Placement API provides endpoints to retrieve information about available placements within the Particular Audience Retail Media platform for any given retailer. Placements represent advertising inventory and/or locations where advertisements can be displayed.

API Endpoint

Method: GET

URL: https://<PA_RM_END_POINT>/retail-media/retailer/{retailerId}/placements

Request Header

Name	Value
Content-Type	application/json
Authorization	Bearer ACCESS_TOKEN

info

Please refer to the Authentication API documentation for bearer token.

Request Parameters

Parameter	Type	Description
retailerId	string	Get the retailer ID from the retailer API

Response Payload

Success Response

• Status Code: 200 OK
• Payload: Returns list of available placements for a retailer in JSON format

{
"payload": [
    {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "placement name",
        "widget": "Popular Items",
        "route": "Home Page",
        "strategy": "Relevance",
        "adSetType": "Sponsored Product",
        "costType": "Cost per mille",
        "availabeSlots": [2, 0, 1, 3, 7, 6, 4, 5],
        "cost": 0.5,
        "status": "Active",
    },
    {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "Hero Banner",
        "widget": "Banner",
        "route": "Home Page",
        "strategy": "Fixed",
        "adSetType": "Sponsored Display",
        "costType": "Cost per click",
        "availabeSlots": [1],
        "cost": 0.5,
        "status": "Active",
        "isKeywordTargetingEnabled": false,
        "startDate": "2025-02-20",
        "endDate": "2025-02-21"
        "specialRates": [
            {
                "title": "special rate title",
                "specialCost": 2.00,
                "startDate": "2025-02-20",
                "endDate": "2025-02-21",
                "id": "xxxxxxxxxxxxxxxxxxxxxxxxx"
            }
        ],
        "dimension": "360x600",
        "displayDimensionType": "IAB Standerd",
    },
  ]
}

Response Parameters

Parameter	Type	Description
id	GUID	System generated unique identifier for the retailer
name	string	Name of the retailer.
widget	string	Name of the widget where the placement is located.
route	string	Name of the route where the placement is located.
strategy	string	Advertising strategy used for the placement.
adSetType	string	Type of ad set associated with the placement.
costType	string	Type of cost associated with the placement.
availabeSlots	Array	List of available slots for the placement.
cost	float	Cost associated with the placement.
status	string	Status of the placement.
startDate	string	Start date for the placement. Only available for Fixed strategy.
endDate	string	End date for the placement. Only available for Fixed strategy.
specialRates	Array	List of special rates for the placement. Only available for Fixed strategy.
dimension	string	Dimension of the placement. Available for Sponsored Display AdSet type.
displayDimensionType	string	Type of dimension used for the placement. Available for Sponsored Display AdSet type.
isKeywordTargetingEnabled	boolean	Indicates if keyword targeting is enabled for the placement. Available for Sponsored Display AdSet type.

Error Response

If an error occurs, the API will return an appropriate status code along with an error message.

• Sample Error Response (400 Bad Request):

{
  "errors": [
    "Error message 1",
    "Error message 2"
  ],
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "xxxxxxxxxxxxxxxxxxx"
}

Example Usage (JavaScript)

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "BEARER YOUR_ACCESS_TOKEN");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect:'follow'
};

fetch("https://<PA_RM_END_POINT>/retail-media/retailer/{retailerId}/placements", requestOptions)
  .then(response => response.json())
  .then(result=> { 
    console.log(result);
  })
  .catch(error => console.log('error', error));