# 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\]

<p class="callout warning">The **Headsup** and **Unlimited Playlist** endpoints must be enabled by Adhese support before they can be used.</p>

## Assets download endpoint

<p class="callout warning">To ensure that the assets are included in the response, the '**Use in heads-up file**' setting must be enabled at format level. This action can be performed by all admin users in the Adhese UI.</p>

```markdown
https://headsup-[customer].adhese.org/api/headsup/download-list/sl[positioncode]
```

<table id="bkmrk-parameters-value-req"><colgroup><col style="width: 20.5192%;"></col><col style="width: 65.6343%;"></col><col style="width: 13.8465%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Parameters</td><td style="height: 29.7969px;">Value</td><td>Required</td></tr></thead><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">customer</td><td style="height: 29.7969px;">The name of your Adhese account</td><td>Yes</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">position code</td><td style="height: 29.7969px;">The code of the position you wish to request: \[location code\]\[optional position code\]-\[format code\]. This value is always prefixed by 'sl'.</td><td>Yes</td></tr></tbody></table>

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:

```bash
{
    "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 endpoints

#### With an amount limit

```markdown
https://ads-[customer].adhese.com/m/stack/sl[positioncode]/pi[playerid]?max_ads=[amount]
```

<table id="bkmrk-parameters-value-req-1"><colgroup><col style="width: 20.2719%;"></col><col style="width: 65.1412%;"></col><col style="width: 14.5868%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Parameters</td><td style="height: 29.7969px;">Value</td><td style="height: 29.7969px;">Required</td></tr></thead><tbody><tr style="height: 29.7969px;"><td class="align-left">customer</td><td class="align-left">The name of your Adhese account</td><td class="align-left">Yes</td></tr><tr style="height: 46.5938px;"><td class="align-left">position code</td><td class="align-left">The code of the position you wish to request is \[location code\]-\[format code\]. This value is always prefixed by 'sl'.</td><td class="align-left">Yes</td></tr><tr style="height: 29.7969px;"><td class="align-left">max\_ads</td><td class="align-left">The maximum number of ads you wish to request</td><td class="align-left">Yes</td></tr><tr style="height: 29.7969px;"><td class="align-left">player ID</td><td class="align-left">The ID of the player. The value must be prefixed by a two-letter code. Adhese support needs to configure this code.</td><td class="align-left">No</td></tr></tbody></table>

The playlist endpoint returns a subset of DOOH campaigns at the requested DOOH position. The JSON response consists of an array named "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 ads to be returned. 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 returned for each campaign must be configured in the ad server using an advar template.

An example response:

```json
{
    "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

```markdown
https://ads-[customer].adhese.com/e/stack/sl[positioncode]/pi[playerid]
```

<table id="bkmrk-parameters-value-req-2" style="width: 100%;"><colgroup><col style="width: 20.2622%;"></col><col style="width: 65.1967%;"></col><col style="width: 14.5411%;"></col></colgroup><thead><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Parameters</td><td style="height: 29.7969px;">Value</td><td style="height: 29.7969px;">Required</td></tr></thead><tbody><tr style="height: 29.7969px;"><td class="align-left">customer</td><td class="align-left">The name of your Adhese account</td><td class="align-left">Yes</td></tr><tr style="height: 46.5938px;"><td class="align-left">position code</td><td class="align-left">The code of the position you wish to request: \[location code\]-\[format code\]. This value is always prefixed by 'sl'.</td><td class="align-left">Yes</td></tr><tr style="height: 29.7969px;"><td class="align-left">player ID</td><td class="align-left">The ID of the player. Value needs to be prefixed by a 2-letter code. Adhese support needs to configure this code.</td><td class="align-left">No</td></tr></tbody></table>

The response markup for the playlist endpoint without a limit is identical to the one with a limit. You will however receive all available ads rather than a subset.