The endpoint also accepts **GET requests,** where the slots and parameters are encoded in the URL path instead of a body. We prefer the POST request but documentation can be retrieved
### Request body The POST body is a JSON object with up to three top-level properties: ```json { "slots": [ { "slotname": "some_slot" }, ... ], "parameters": { "kw": [ "cheese", "wine" ], ... }, "user": { "ext": { "eids": [] } } } ```| Property | Required | Purpose |
|---|---|---|
| `slots` | **Yes** | The ad placements you are requesting |
| `parameters` | No | Request-level targeting data (page, user, context) |
| `user` | No | External user IDs for downstream buyers (open market) |
⚠️ Each `slotname` may appear only once per request. Duplicates cause the request to be rejected with status `442`.
### parameters An object of targeting attributes describing the page, user, or context. Keys are **fixed two-character codes** defined in your Adhese account; values are **always arrays of strings**. All parameters are optional — omit a key entirely, or send an empty array, when there is nothing to pass. ```json "parameters": { "kw": ["cheese", "wine"], "mi": ["ABCDEF123456"] } ``` In this example, `kw` carries search keywords and `mi` a member ID. Reserved parameter codes are listed on [Request target parameters](https://documentation.adhese.org/books/integration-setup/page/request-target-parameters). ### Slot-level parameters A slot object can carry its own `parameters` property with the same structure. For each slot, request-level and slot-level parameters are **merged**. Use this for attributes that differ per placement, such as position on the page: ```json "slots": [ { "slotname": "some_slot", "parameters": { "ps": ["top"] } }, { "slotname": "another_slot", "parameters": { "ps": ["bottom"] } } ] ``` ### user Reserved for passing identifiers from external ID providers to buyers further down the chain, mainly in an open-market context: ```json "user": { "ext": { "eids": [] } } ``` If you think you need this, contact [Adhese Support](https://documentation.adhese.org/books/introduction/page/adhese-support) before implementing. ### Complete request example ```json { "slots": [ { "slotname": "homepage_banner" }, { "slotname": "homepage_rectangle_top" }, { "slotname": "homepage_rectangle_bottom" }, { "slotname": "homepage_halfpage", "parameters": { "ps": ["right"] } } ], "parameters": { "id": ["1234567890ABCD"], "ct": ["computers", "laptops"], "kw": ["cheese", "wine"] } } ``` Here `id` is a user ID, `ct` product categories, and `kw` search keywords. ## Making a GET request The GET version of the ad request contains the same information as the POST version, **slot level parameters are however not supported.** Example request ```html https://ads-[account].adhese.com/json/sl_sdk_example_-leaderboard/ctsports;soccer?t=244.18664863333106 ```| Section | Meaning | Details |
| https://ads-\[account\].adhese.com | Ads domain | The domain is either the default ads domain for your account or a configured first-party domain. More info on first-party domains can be found here. |
| /json/ | Endpoint identifier | |
| /sl\[location code\]-\[format code\]/ | Slots | This section can be added more than once. Each placement starts with the prefix 'sl', followed by the full slot code. |
| /ctsports;soccer/ | Target(s) | This section can be added more than once. Each target section starts with its predefined prefix and is followed by either one value or a list of values separated by ';'. |
| ?t=\[timestamp\] | Timestamp | A timestamp to avoid caching issues |
| Code | Meaning | Details |
|---|---|---|
| `200` | OK | Body contains an array of ads. If no ads are available, the array is empty — an empty array is a **successful** response, not an error. |
| `442` | Duplicate slots | One or more `slotname` values appear more than once. Header `x-adhese-bad-request` lists the duplicates. |
| `454` | No slots | The request body contains no slots. Header `x-adhese-bad-request` contains `slots cannot be empty`. |
| `500` | Internal server error | If this was a debug request, check the debug log; otherwise contact Adhese Support. |
| Attribute | Description |
|---|---|
| `slotName` | The slot this ad belongs to. Use it as the key to match responses to the slots in your request when requesting multiple slots at once. |
| `tag` | The ad markup, returned as a string. For display ads this is typically an HTML fragment to insert into the slot's container. For video/audio it is a VAST-compliant XML document; for native ads it is a JSON object (delivered as a string that your application must parse). |
| `width` | Width of the ad container in pixels, required for correct display. |
| `height` | Height of the ad container in pixels, required for correct display. |
| `trackedImpressionCounter` | Unique URL to call when the ad is **added to the page**, even if not yet visible. Registers an IAB *paid impression*. Fire-and-forget: the call can be asynchronous and the response ignored. |
| `viewableImpressionCounter` | Unique URL to call when the ad has been **at least 50% in the viewport for at least one second**. Registers an IAB *viewable impression*. Fire-and-forget. |
| `clickTag` | Unique URL that counts a click and redirects the user to the ad's landing page. Use it as the href wrapping the creative. In applications without links, the URL can be called directly to register the click, ignoring the response. |