Request API: AD endpoint

AD Endpoint

The AD endpoint is used for integrations that can't parse a JSON response and require the response toin bea 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 ~~specific markup.~~XML.

GETRequest requestmethod

The AD endpoint ~~can~~supports GET requests only. beAs ~~used by using a Get request and - similar to~~with the GET version of the JSON ~~endpoint~~endpoint, ~~- slot~~ slot-level parameters are not ~~supported.~~ supported.

URL structure

~~The~~A ~~GET~~request ~~version~~URL ofis built from the adsections ~~request~~below, ~~contains~~in ~~the~~order. ~~same~~Sections ~~information~~marked asrepeatable ~~the~~can ~~POST~~appear ~~version~~more ~~with~~than ~~one limitation:~~
~~slot level parameters are not supported.~~once.

~~Example request~~

https://ads-[account].adhese.com/ad/sl_sdk_example_-leaderboard/ctsports;soccer?t=244.18664863333106

~~section can be added more than once. Eachsection can be added more than once. Each~~

	Section		Repeatable	Description
`https://ads-[account].adhese.com`	No	The domain is— either the default ads domain for your account or a configured first-party domain. ~~More~~See ~~info on first-~~First-party domains ~~can~~for bemore ~~found here.~~info.
`/ad/`	No	Fixed path segment that selects the AD endpoint.
`/sl[location code]-[format code]/`	~~This~~No	A placement ~~starts~~(slot). Starts with the prefix ~~'sl'~~`sl`, followed by the full slot code.
_{/ctsports;soccer/} `ct[value];[value]/`	~~This~~Yes	A target ~~section~~section. ~~starts~~Starts with its predefined prefix (e.g. `ct`) and is followed by ~~either~~a ~~one~~single value or a list of values separated by '`;'`. Add one section per target group you want to pass.
_{?t=[timestamp]}	No	A ~~timestamp~~timestamp, used to avoid caching ~~issues~~issues.

Example request

https://ads-demo.adhese.com/ad/sldemo.com_kitchen-billboard/dtdesktop

Broken 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).

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	~~Body~~The body contains ~~an array of~~the ads. If no ads are available, the ~~array~~response iscontains ~~empty~~no ads — an empty ~~array~~response is a successful ~~response,~~result, not an error.
`454`	No slots	The request ~~body~~ contains no slots. ~~Header~~The `x-adhese-bad-request` header contains `slots cannot be empty`.
`500`	Internal server error	~~If this was~~For a debug request, check the debug ~~log;~~log. ~~otherwise~~Otherwise, contact Adhese Support.

Error handling

When handling errors programmatically, read the x-adhese-bad-request response header for the specific error message.