Skip to main content

DOOH endpoints

Adhese has 3 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 limited amount 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 endpoint and the unlimited playlist endpoint need to be enabled by Adhese support before itthey can be used. 

Assets download endpoint

The "Use in headsup file" setting needs to be enabled on format level to make sure the assets become available in the response. This action can be performed in the Adhese UI by all admin users.

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 materials for the campaigns running on the requested DOOH position. The JSON response consists of an array "media" which can be empty or filled with several "ad" objects depending on the amount of active campaigns.

An example response:

{
    "media": [
        {
            "ad": {
                "id": "https://pool-[account].adhese.com/pool/lib/97_3rd_1.png",
                "mime": "image/png",
                "curl": "https://pool-[account].adhese.com/pool/lib/97_3rd_1.png",
                "checksum": "9d3e92f16382e9dbd480cdc3a6b2beabcd2c11c2b1e65a65812404240ff5db"
            }
        },
        {
            "ad": {
                "id": "https://pool-[account].adhese.com/pool/lib/56_2nd_1.mp4",
                "mime": "video/mp4",
                "curl": "https://pool-[account].adhese.com/pool/lib/56_2nd_1.mp4",
                "checksum": "925b53ac94eec59a095464a937c106c22b77b95455f2ee38e5cfb374ff3065"
            }
        }
    ]
}

Playlist endpoint

With 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: [location code]-[format code] This value is always prefixed by 'sl'. Yes
max_ads The maximum amounts of ads you wish to request Yes
player ID The ID of the player. Value needs to be prefixed by a 2 letter code. This code needs to be configured by Adhese support. No

The playlist endpoint returns a subset of DOOH campaigns running on the requested DOOH position. The JSON response consists of an array "ads" which can be empty or filled with several objects depending on the amount of active campaigns.

The maximum amount of returned ads is defined by the max_ads parameter. A separate configuration on the adserver can be activated to make sure this value never goes above a specific limit.

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

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

The structure of the JSON object that is returned for each campaign needs to be configured in the adserver by use of an advar template.

An example response:

{
    "ads": [
        {
            "id": "https://pool-[account].adhese.com/pool/lib/1_2nd_2.mp4",
            "dur": 10,
            "prio": 15,
            "externalKey": "CI-X",
            "proofOfPlay": "https://ads-[account].adhese.com/track/1//sl1/tlnone/A2?1718190774050",
            "error": "https://ads-[account].adhese.com/track/1-PLAY_ERROR_[ERRORCODE]//sl1/?1718190774050"
        },
        {
            "id": "https://pool-[account].adhese.com/pool/lib/2_2nd_2.mp4",
            "dur": 15,
            "prio": 10,
            "externalKey": "CI-O",
            "proofOfPlay": "https://ads-[account].adhese.com/track/2//sl1/tlnone/A2?1718190774050",
            "error": "https://ads-[account].adhese.com/track/2-PLAY_ERROR_[ERRORCODE]//sl1/?1718190774050"
        }
    ]
}


Without 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. This code needs to be configured by Adhese support. No

The response for the playlist endpoint without limit is identical as the one with a limit. You will however receive all available ads instead of only a subset.

Back to top