Skip to main content

DOOH endpoints

Adhese has 2 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
    https://ads-[customer].adhese.com/m/stack/sl[positioncode]?max_ads=[amount]

The headsup endpoint needs to be enabled by Adhese support before it can be used. If not enabled, the endpoint will redirect to the adhese.eu website.

The "Use in headsup file" setting needs to be activated 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.

Assets download endpoint

https://headsup-[customer].adhese.org/api/headsup/download-list/sl[positioncode]
ParametersValueRequired
customerThe name of your Adhese accountYes
position codeThe 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

https://ads-[customer].adhese.com/m/stack/sl[positioncode]/pi[playerid]?max_ads=[amount]
ParametersValueRequired
customerThe name of your Adhese accountYes
position codeThe code of the position you wish to request: [location code]-[format code] This value is always prefixed by 'sl'.Yes
max_adsThe maximum amounts of ads you wish to requestYes
player IDThe 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"
        }
    ]
}
Back to top