Request API: AD endpoint
The AD endpoint is used for integrations that can't parse a JSON response and require the response in a specific markup instead. It is typically used for video and audio setups, where ads are requested by media players and follow the VAST protocol in XML.
The API is public and requires no authentication and cookies are not required for an integration to work.
Request method
The AD endpoint supports GET requests only. As with the GET version of the JSON endpoint, slot-level parameters are not supported.
Unlike the JSON endpoint, only one placement can be retrieved with each call
URL structure
A request URL is built from the sections below, in order. Sections marked repeatable can appear more than once.
| Section | Repeatable | Description |
|---|---|---|
https://ads-[account].adhese.com |
No | The domain — either the default ads domain for your account or a configured first-party domain. See First-party domains for more info. |
/ad/ |
No | Fixed path segment that selects the AD endpoint. |
/sl[location code]-[format code]/ |
No | A placement (slot). Starts with the prefix sl, followed by the full slot code. |
/ct[value];[value]/ |
Yes | A target section. Starts with its predefined prefix (e.g. ct) and is followed by a single value or a list of values separated by ;. Add one section per target group you want to pass. |
?t=[timestamp] |
No | A timestamp, used to avoid caching issues. |
Example request
https://ads-demo.adhese.com/ad/sldemo.com_kitchen-billboard/dtdesktopBroken down:
| Part | Meaning |
|---|---|
https://ads-demo.adhese.com |
Ads domain for the demo account |
/ad/ |
AD endpoint |
/sldemo.com_kitchen-billboard/ |
Placement: prefix sl, location code demo.com_kitchen, format code billboard |
/dtdesktop/ |
Target section: prefix dt with value desktop |
Response
A successful request returns the ads in the requested markup (VAST XML for video/audio setups).
This markup is determined by the advar template used to create the banner that is returned by the request.
If no ads are available, the response contains no ads. This is still a successful 200 response, not an error.
Response codes
| Code | Name | Description |
|---|---|---|
200 |
OK | The body contains the ads. If no ads are available, the response contains no ads — an empty response is a successful result, not an error. |
454 |
No slots | The request contains no slots. The x-adhese-bad-request header contains slots cannot be empty. |
500 |
Internal server error | For a debug request, check the debug log. Otherwise, contact Adhese Support. |
Error handling
When handling errors programmatically, read the x-adhese-bad-request response header for the specific error message.