Skip to main content

Digital Out Of Home

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 relevant ads are 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]
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] Yes

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

Headsup functionality 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 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]
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] Yes
max_ads The maximum amounts of ads you wish to request Yes
player ID The ID of the player. Can be used for logging, targeting and mapping 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