Skip to main content

DOOH endpoints

Adhese has three endpoints in place for DOOH integrations:

  1. Assets Download Endpoint (aka Headsup request)
    https://headsup-[customer].adhese.org/api/headsup/download-list/sl[positioncode]

  2. Playlist Endpoint with a limited number of ads
    https://ads-[customer].adhese.com/m/stack/sl[positioncode]?max_ads=[amount]

  3. Playlist Endpoint with unlimited amount of ads
    https://ads-[customer].adhese.com/e/stack/sl[positioncode]

The Headsup and Unlimited Playlist endpoints must be enabled by Adhese support before they can be used.

Assets download endpoint

To ensure the assets become available in the response, the "Use in heads-up file" setting must be enabled on the format level. All admin users can perform this action in the Adhese UI.

https://headsup-[customer].adhese.org/api/headsup/download-list/sl[positioncode]
Parameters Value Required
customer The name of your Adhese account Yes
position code The code of the position you wish to request: [location code]-[format code]. This value is always prefixed by 'sl'. Yes

The headsup endpoint returns all the materials for the campaigns running on the requested DOOH position. The JSON response consists of an array "media" that may be empty or populated with multiple ad objects, depending on the number of active campaigns.

An example response:

{
    "media":[
        {
            "ad":{
                "id":"https://pool-demo.adhese.com/pool/lib/562_2nd_1.mp4",
                "mime":"video/mp4",
                "curl":"https://pool-demo.adhese.com/pool/lib/562_2nd_1.mp4",
                "filesize": 15470592,
                "checksum":"071f717962db99cc137d138696d33209f2e4818d42a54f70dfa6606eeb1b640b"
            }
        },
        {
            "ad":{
                "id":"https://pool-demo.adhese.com/pool/lib/560_2nd_1.mp4",
                "mime":"video/mp4",
                "curl":"https://pool-demo.adhese.com/pool/lib/560_2nd_1.mp4",
                "filesize": 15470592,
                "checksum":"4e78745a33518ff22c1c9f39852a49c1c0fadd0adf722e3394ad1215d5e5ff5b"
            }
        },
        {
            "ad":{
                "id":"https://pool-demo.adhese.com/pool/lib/561_2nd_1.mp4",
                "mime":"video/mp4",
                "curl":"https://pool-demo.adhese.com/pool/lib/561_2nd_1.mp4",
                "filesize": 6582272,
                "checksum":"64d2eab6d51b208c0cec3fc4d64c53381e5d41ae2a1d4c5b7704b1818bdb6158"
            }
        }
    ]
}

Playlist endpoint

With an amount limit

https://ads-[customer].adhese.com/m/stack/sl[positioncode]/pi[playerid]?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
max_ads The maximum number of ads you wish to request Yes
player ID The ID of the player. The value needs to be prefixed by a 2-letter code. Adhese support needs to configure this code. No

The playlist endpoint returns a subset of DOOH campaigns at the requested DOOH position. The JSON response consists of an array "ads" which can be empty or populated with multiple objects depending on the number of active campaigns.

The max_ads parameter defines the maximum number of returned ads. A separate configuration on the adserver can be activated to ensure this value never exceeds a specific limit.

A player ID can be provided as an optional parameter in the request. This ID can be used for a number of purposes:

  • Targeting campaigns on specific players
  • Creating reports on player level
  • Server-side mapping of additional data. This data is then available for targeting and reporting

The structure of the JSON object that is returned for each campaign must be configured in the adserver using an advar template.

An example response:

{
    "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",
            "frequency":"1;1;1",
            "starttime":"0:00",
            "stoptime":"not set"
        },
        {
            "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",
            "frequency":"2;1;1",
            "starttime":"not set",
            "stoptime":"not set"
        },
        {
            "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",
            "frequency":"2;1;1",
            "starttime":"not set",
            "stoptime":"not set"
        }
    ]
}


Without an amount limit

https://ads-[customer].adhese.com/e/stack/sl[positioncode]/pi[playerid]
Parameters Value Required
customer The name of your Adhese account Yes
position code The code of the position you wish to request: [location code]-[format code]. This value is always prefixed by 'sl'. Yes
player ID The ID of the player. Value needs to be prefixed by a 2-letter code. Adhese support needs to configure this code. No

The response for the playlist endpoint without a limit is identical to the one with a limit. However, you will receive all available ads rather than a subset.

Back to top