Request API

For integrations where you don't want to use an SDK or other library, we provide the request endpoint so you can build the request URLs yourself. Both GET and POST requests are supported, but there is a slight difference between them.

POST endpoint

This endpoint provides access to the ad server and gateway functionality for server applications. This functionality allows implementers to send an HTTP POST request to their Adhese endpoint, returning an array of ads for the requested ad slots.

The POST body can contain a number of parameters, the structure of which is documented below.

The API is public and requires no authentication. Any client-side framework that can interpret a JSON response can request the same endpoint.

Endpoint URL

To obtain the endpoint URL for your account, contact Adhese Support.

Default look of the endpoint URL:

https://ads-{customer}.adhese.com/json/

Request Type

HTTP POST request over an HTTPS connection. In a production environment, no cookies are needed; all data is passed in the request body.

For debugging purposes, add a ‘set-cookie’ header with the value ‘debugKey=[any_value]’. This will make all activity from your requests available in Gateway Debug Logging.

Do not use this debug cookie for production requests. If used on a large scale, it will add significant latency to your responses.

POST Body

The body of your POST request can contain JSON following a fixed structure. There are three main properties.

{
    "slots": [
        {
            "slotname": "some_slot"
        },
        ...
    ],
    "parameters": {
        "kw": [
        "cheese",
        "wine"
        ],
        ...
    },
    "user": {
      "ext": {
        "eids": []
      }
    }
}

slots

An array of slot objects containing all the ad units required for a given page or state of the end-user application. At least one slot is required.

Each slot contains at least a 'slotname', which is a unique identifier for a specific advertisement placement. This string is stored in the Adhese database and used for targeting campaigns.

"slots": [
        {
            "slotname": "some_slot"
        },
        {
            "slotname": "another_slot"
        }
    ]

parameters

An object that contains a set of properties and their corresponding array of values. The purpose of this object is to define one or more attributes that tell you something about the page, user, context, etc.

The parameter keys are fixed two-character codes defined in your Adhese account. The value is always an array of strings. All parameter properties are optional. You can leave them out if they are empty or irrelevant, or send an empty array as value.

"parameters": {
    "kw": [
        "cheese",
        "wine"
    ],
    "mi": [
        "ABCDEF123456"
    ]
}

In the example above, “kw“ is used for “search keyword“and “mi” for “member id.”

slot level parameters

A slot can also contain a 'parameters' attribute that follows the same structure. Parameters can be defined at both the request and slot levels. The values of these parameters will be merged for each corresponding slot.

"slots": [
    {
        "slotname": "some_slot",
        "parameters": {
            "ps": "top"
        }
    },
    {
        "slotname": "another_slot",
        "parameters": {
            "ps": "bottom"
        }
    }
]

user

The user property is reserved for situations where external ID providers are available, and their identifiers need to be transferred to buyers further down the line. This is mainly useful in an open market context. For more info, please contact our Support Team.

Example of a complete request body

{
    "slots": [
        {
            "slotname": "homepage_banner"
        },
        {
            "slotname": "homepage_rectangle_top"
        },
        {
            "slotname": "homepage_rectangle_bottom"
        },
        {
            "slotname": "homepage_halfpage",
            "parameters": {
                ...
            }
        }
    ],
    "parameters": {
        // Example user ID
        "id": [
            "1234567890ABCD"
        ],
        // Example product categories
        "ct": [
            "computers",
            "laptops"
        ],
        // search keywords
        "kw": [
            "cheese",
            "wine"
        ]
    }
}

Response Codes

200

All is OK. If no advertisements are available, an empty array will be in the response body.

454

No slots were added to the request body, so no advertisements can be returned. An error message containing the message' slots cannot be empty' is added to the response as header ‘x-adhese-bad-request’.

442

A duplicate slotname has been used for one or more slots. An error message is added to the response as header ‘x-adhese-bad-request’ containing message ‘request contains duplicate slots: [list of duplicate slots]’

500

Internal server error. Further information could be available in the debug log if it was a debug request or via Adhese Support.

Response Object

To be moved to its own page

The response object contains a number of attributes. A full description can be found here: https://github.com/adhese/sdk#response-object-structure.

The relevant attributes for a server-side integration are the following:

slotName

A string containing the name of the slot for which this response is intended. When requesting multiple slots simultaneously, this can be used as a key to link the responses to the slots you have added to the request body.

tag

The ad markup used to render the advertisement on the client is returned as a string and can be of any type interpretable by the client or requester.

For typical web and display advertising, the markup is usually a fragment of HTML that can be inserted into a container on the page.

For video or audio advertising, the markup is usually a VAST-compliant XML document.

For native advertising, the markup typically comprises a JSON object containing all the elements required by a client application or browser script to render the ad correctly.

The markup can contain JSON as a string, which the application consuming the responses must parse to get the actual JSON.

width

height

trackedImpressionCounter

The client application can call a unique URL when the ad is added to a page, even if it is not yet visible and the user has to scroll to see it.

The call to the URL can be asynchronous, and the response can be ignored.

The call to this URL registers a 'paid impression' for a specific ad, as defined by the IAB.

viewableImpressionCounter

The client application can call a unique URL when the ad is visible in the viewport for at least 50% and for at least one second. The call to the URL can be asynchronous, and the response can be ignored.

A call to this URL will register a 'viewable impression', a metric defined by the IAB and used in digital advertising.

clickTag

The clickTag attribute contains a unique URL that can be used to create a link that is counted as a 'click' on the ad and redirects the user to the ad's landing page.

When implemented in an application that does not use links or URLs, the clickTag URL can register a click while ignoring the response, just like the impression counters.

Event tracking

To be moved to its own page

Creating an Event Tracking URL

You can create unique URLs based on the JSON output to register any event related to the ad once it is rendered on screen.

A tracking event URL structure looks like this:

https://[ad_request_host]/track-[your_event_string]/[response.id]/sl[response.slotID]/II[response.impressionID]

Adding an Event Tracking URL to a template

In an Advar or HTML5 template, event-tracking URLs can be created using server-side request parameters. A tracking event would then look like this:

https://[adheseDomain:ad_host]/track-[your_event_string]/[adheseLogID]/sl[adheseReplace:sl]/II[adheseReplace:II]

Example of a full response object

[
    {
        "dm": "dmDMGo2g0c0;ADV0",
        "adType": "714x224",
        "adFormat": "714x224",
        "timeStamp": "1642511791000",
        "share": "0",
        "priority": "0",
        "orderId": "2",
        "adspaceId": "2",
        "adspaceKey": "CI-ADH-12345678",
        "body": "",
        "trackingUrl": "",
        "tracker": "https://ads-demo.adhese.com/track/121//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/?t=1642610778623",
        "extraField1": "",
        "extraField2": "",
        "altText": "",
        "height": "224",
        "width": "714",
        "tag": "{    '_links': {        'self': {            'href': 'https://ads-demo.adhese.com/raylene//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/ad121-4/UR/acties/'        }    },    'resourceType': 'Editorial',    'type': 'HalfWidthSmallResponsiveEditorial',    'position': {        'x': 'left',        'y': 'top'    },    'contentSize': 'half',    'color': 'drop',    'text': {        'title': 'Maak kans op een exclusieve Bud Dreams Jacket',        'body': 'Bekijk de actie'    },    'images': [        {            'title': '<IMAGE_TITLE>',            'width': 714,            'height': 224,            'link': {                'href': 'https://pool-demo.adhese.com/pool/lib/4_2nd_1.jpg'            }        },        {            'title': '<IMAGE_TITLE>',            'width': 714,            'height': 224,            'link': {                'href': 'https://pool-demo.adhese.com/pool/lib/4_2nd_1.jpg'            }        }    ],    'navItem': {        'title': 'Bekijk de actie',        'link': {            'href': 'https://ads-demo.adhese.com/raylene//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/ad121-4/URhttps://ah.nl/acties/winactie-bud'        }    }}",
        "tagUrl": "https://pool-demo.adhese.com/pool/lib/4_0.advar",
        "heightLarge": "224",
        "widthLarge": "714",
        "libId": "4",
        "id": "121",
        "advertiserId": "0",
        "orderProperty": "brands-budweiser",
        "ext": "advar",
        "swfSrc": "https://pool-demo.adhese.com/pool/lib/4_0.advar",
        "url": "https://ads-demo.adhese.com/raylene//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/ad121-4/UR",
        "clickTag": "https://ads-demo.adhese.com/raylene//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/ad121-4/UR",
        "swfSrc2nd": "https://pool-demo.adhese.com/pool/lib/4_2nd_1.jpg",
        "swfSrc3rd": "",
        "swfSrc4th": "",
        "poolPath": "https://pool-demo.adhese.com/pool/lib/",
        "comment": "",
        "adDuration": "0",
        "adDuration2nd": "0",
        "adDuration3rd": "0",
        "adDuration4th": "0",
        "orderName": "Example Bud Dream Jacket",
        "creativeName": "Bud Dream Jacket",
        "deliveryMultiples": "free",
        "deliveryGroupId": "o2g0c0",
        "adspaceStart": "1630447200000",
        "adspaceEnd": "1643669999000",
        "swfSrc5th": "",
        "swfSrc6th": "",
        "adDuration5th": "0",
        "adDuration6th": "0",
        "width3rd": "0",
        "width4th": "0",
        "width5th": "0",
        "width6th": "0",
        "height3rd": "0",
        "height4th": "0",
        "height5th": "0",
        "height6th": "0",
        "slotName": "ah.nl-test_bonus_bonusregulier_left-714x224",
        "slotID": "6",
        "impressionCounter": "https://ads-demo.adhese.com/track/121//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/?t=1642610778623",
        "trackedImpressionCounter": "https://ads-demo.adhese.com/track/121//sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/?t=1642610778623",
        "viewableImpressionCounter": "https://ads-demo.adhese.com/track/121-Adhese_IABview/sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/?t=1642610778623",
        "additionalCreatives": [],
        "origin": "JERLICIA",
        "originData": {},
        "auctionable": "true",
        "additionalViewableTracker": "",
        "additionalCreativeTracker": "https://ads-demo.adhese.com/track/121-additional-4/sl6/brChrome/brChrome97/brOSX/brdesktop/dtdesktop/ogcontrol/II19656e55-a3cd-4a39-8ed5-28f575a2e9b1/tlnone/ctaardappel-groente-fruit/ctkruiden-knoflook-pepers/umknown/kwkaas/om0/cuc/cxveel-gebruikt:snel/cxkeuken:italiaans/cxmomenten:wat_eten_we_vandaag/id1234567890ABCD/miAH0099887766/A2127.68.78.84/?t=1642610778623",
        "extension": {
            "mediaType": "banner",
            "prebid": {
                "cpm": {
                    "amount": "13.047",
                    "currency": "EUR"
                }
            }
        }
    }
]

Typescript Web SDK

Prebid

Request API

VAST

Instream & Outstream

DOOH endpoints

Request API

POST endpoint

Endpoint URL

Request Type

POST Body

slots

parameters

slot level parameters

user

Example of a complete request body

Response Codes

200

454

442

500

Response Object

slotName

tag

width

height

trackedImpressionCounter

viewableImpressionCounter

clickTag

Event tracking

Creating an Event Tracking URL

Adding an Event Tracking URL to a template

Example of a full response object

No Comments