Request API: Stack endpoint
The stack endpoint allows you to request one position for which Adhese will return a list of ads. There are 2 versions:
- /m/stack/: returns a limited amount of ads
- /e/stack/: returns an unlimited1 amount of ads2
1 The adserver rules still apply and will influence which campaigns are part of the response. Not all booked campaigns are necessarily part of the returned array.
2 The /e/stack/ endpoint must be enabled by Adhese support before it becomes available
m/stack endpoint
https://ads-[customer].adhese.com/m/stack/sl[positioncode]/[target prefix][target value]?max_ads=[amount]| Parameters | Value | Required |
| customer | The name of your Adhese account | Yes |
| position code | The code of the position you wish to request is [location code]-[format code]. This value is always prefixed by 'sl'. | Yes |
| custom target | Similar to the basic JSON GET endpoint, the stack request can contain target information by adding a prefix followed by a value. More values can be separated with a ; | No |
| max_ads1 | The maximum number of ads you wish to request | Yes |
1 A configuration on the adserver can be activated to ensure the max_ads value never exceeds a specific limit. When the parameter is left empty, the configured limit will be used instead.
e/stack endpoint
https://ads-[customer].adhese.com/e/stack/sl[positioncode]/[target prefix][target value]| Parameters | Value | Required |
| customer | The name of your Adhese account | Yes |
| position code | The code of the position you wish to request is [location code]-[format code]. This value is always prefixed by 'sl'. | Yes |
| custom target | Similar to the basic JSON GET endpoint, the stack request can contain target information by adding a prefix followed by a value. More values can be separated with a ; | No |
Stack response
Returned code
The response contains JSON code: an ads array that will either be empty or populated with one or more objects, depending on the number of active campaigns.
The structure of the objects within the array is determined by the advar template used when setting up the creatives.
An example response used in a DOOH setup
{
"ads":[
{
"id":"https://pool-demo.adhese.com/pool/lib/562_2nd_1.mp4",
"dur":28.07,
"prio":15,
"booking_prio":0,
"publisher":"1",
"key":"",
"proofOfPlay":"https://ads-demo.adhese.com/track/3474/sl357/tlnone/piplayer_id/A2?1746011926824",
"error":"https://ads-demo.adhese.com/track/3474-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
},
{
"id":"https://pool-demo.adhese.com/pool/lib/561_2nd_1.mp4",
"dur":11.45,
"prio":15,
"booking_prio":0,
"publisher":"1",
"key":"",
"proofOfPlay":"https://ads-demo.adhese.com/track/3444/sl357/tlnone/piplayer_id/A2?1746011926824",
"error":"https://ads-demo.adhese.com/track/3444-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
},
{
"id":"https://pool-demo.adhese.com/pool/lib/560_2nd_1.mp4",
"dur":18.85,
"prio":15,
"booking_prio":0,
"publisher":"1",
"key":"",
"proofOfPlay":"https://ads-demo.adhese.com/track/3455/sl357/tlnone/piplayer_id/A2?1746011926824",
"error":"https://ads-demo.adhese.com/track/3455-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
}
]
}Sorting the returned list
The order in which the ads array is populated can be be configured by using the sequence property in the advar template.
As value you can use a number that is filled in through the advar form, or use one of the Adhese macro's that return an ID.
When the sequence property is added and given a value, the adserver will sort the available ads based on its value. In the example below we use the CREATIVE ID to sort the array from lowest ID to highest ID.
"sequence": <ADHESE_LIB_ID>The sequence property is only used by the adserver and will be removed before the response is returned