Display

API Integration

In the API integration model, AdsHero is only responsible for selecting ads. Rendering is handled by the service that queries AdsHero for ads.

This is the recommended integration method: it provides the greatest flexibility in presenting ads on the page.

A basic ad request looks like this:

POST https://dispatcher.ahevds.com/v1/banner/dsa/raw/batch HTTP/2
Content-Type: application/json
cid: {cid}
uid: {uid}

{
  "targeting": [
    {
      "slotHash": "{slotHash}",
      "adCount": 1
    }
  ]
}

curl --location --request POST 'https://dispatcher.ahevds.com/v1/banner/dsa/raw/batch' \
    --header 'Content-Type: application/json' \
    --header 'cid: {cid}' \
    --header 'uid: {uid}' \
    --data '{
      "targeting": [
        {
          "slotHash": "{slotHash}",
          "adCount": 1
        }
      ]
    }'

slotHash is the identifier of the ad unit available in the publisher’s panel on the list of ad units (menu “Slots”).
adCount (value of 1 in the example) is the maximum number of ads to be returned.

The provided endpoint selects ads for the list of slots. The targeting list contains one object for each ad unit (slot) for which ad selection should be carried out.

A single element of the targeting list can contain more parameters. The parameters specified at the slot configuration level should be included in the ad request.

The endpoint accepts headers cid and uid.

Sample API response:

HTTP/1.1 200 
Content-Type: application/json;charset=utf-8

{
  "data": [
    {
      "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
      "ads": [
        {
          "bannerId": "4732",
          "bannerUrl": "https://adshero.com/",
          "mobileDeepLink": "https://adshero.com/",
          "showId": "eyJhbGciOiJSUzUxMiJ9.eyJhZHVuaXQiOiJhRDhJQTFuVHphaUk5RFphdkpmMnllNkdBZlJTenJpZlZyS3AveEdjVS83NFNwR2tsWTdZai9HYzJIQ2hZYzhUNFRXcFppdFNtWTZELzFQTEVKc21TanMvbGZubUNjZWhYSjMvczIwdG1NQ2NqS3BpS2NFa1kzZVN3VXVKbytsbThpY2dUMzdjb0ZZeCtqV3VEcC9aa0lYWnhOMkJvY3lzVThmN2NrL09FY2hWVGtPU0QrTlZSY28yRXVwUTM4QlhnWUJhR2ZRV1hOeFpqdzdvMGdEUkRaMmpTa1FmKzVnT011SEdGbzJwZ0FCTG1aTklFNWlTNFZCbUZRenFDVXVCRkNteE5PQzZTTDdXWGplVVFqT3VwVlhUWnVZTzVsQ0dYcU1Sb0JyUCtaaWljSThHd2NTbFZPSnB5UVRMb1N2eU80VDY2Y3p5blpFWUs1eHJDRGtCZWhDSk1zMkpYbDJzQ1ZMSVlOQzRLMFg1MktTMGRSMXdLMlJZQnVyZGVKM28waldJQ0QvN3ZEaFVuemNnODJCNTJhRjYwZEpkbVQ1cEJ1RldoWlpzcldoT21lQWZTTUxiU0RKWnNZd1ZQdCt0SjVwWGhoclUxYldIaElXckVTd1FTZEs3T3Exd2NROVFiMXJQL1dMR1BtMUpTa2hFQXlUeC9KZlhJK3RXY05JdXlsd1AyYjZ6ZHhFOXB2UDJESDFUT0RnRFBIRzg0ajBMQ1owTkVFT01VbGxjenlzWDNRanJSaVp3OHM4QTBTSEphL1lSV1Q4M3ZlVWdBa2U4dEU2bnpTTXRrMlFGMVh6SzZXbUFtSzNOSFhiNjMzRFdGd3VlcmpKUEVYcmFsOGhYZEJ3L0FlcTU4N2k1cHJOVXlKRG52Zz09IiwidHlwZSI6IkJBTk5FUiJ9.U4VJZH2YvrM50tTLrW5wldAaFgVN12104TLH9L0eRnzLluFkQYyL_WgFvQ90iCvKEHr97W_DrhhJj5J34n2mH_cIMDqxYSIiMxejeHfmx7Rn5xYZjlfrfFjl4eLGorC9jf_ayUvXo-2T7BzZeuwIDlAi3q-BL6nuwShIQ6hg8-vynq5l0QrvCjrMLNqsvUh4bt0IVGDEleVcMByfPw7bo9ZhS0qFwBxTTNKsf6mFuC4pOJrNh6w-vGIPKewfQpkq26jANhjlNIWkAXYCItCza3uVjvCbxjg_9M1PwVofsmxcj1GJmDQN0bNbRoQcxZeOBV1NcuRxdihFu_JV2_bw7w",
          "requestId": "|b1k7w9d6qwCBkAVFANzxRoQWyxYXpX5KyylO.7XZsrc_",
          "slotHash": "8cc4ba26-bb96-46f1-975c-a6a21243bb05",
          "shopId": "cf196098-c935-4ac4-83f2-aece5185602a",
          "lang": null,
          "currency": null,
          "autoPromo": false,
          "bannerLogoUrl": null,
          "bannerImageUrl": null,
          "adFormatId": "0f76d848-0977-422a-8f12-251b5b5c3ca7",
          "bannerProducts": null,
          "images": [
            {
              "width": 930,
              "height": 180,
              "imageId": "1b56a006-f3be-4684-9008-e41e41aab41d.png",
              "imageUrl": "https://prd-cdn-images-prx.ahevds.com/1b56a006-f3be-4684-9008-e41e41aab41d.png"
            }
          ],
          "textFields": [
            {
              "type": "TITLE",
              "value": "First"
            },
            {
              "type": "CTA",
              "value": "CLICK!"
            },
            {
              "type": "BG_COLOR",
              "value": "#ff00ff"
            }
          ]
        }
      ]
    }
  ],
  "meta": null,
  "clientId": "v2.937064567.1728059604"
}

Available parameters:

Name	Description	Allowed values	Example value
`slotHash`	Hash of the ad unit for which ads are being selected.	UUID	`"8cc4ba26-bb96-46f1-975c-a6a21243bb05"`
`adCount`	Maximum number of ads to return.	Whole numbers greater than 0.	`2`
`minAdCount`	Minimum number of ads to return. If there is no minimum number of ads in the response, an empty list will be returned.	Whole numbers greater than 0.	`1`
`searchData`	Search phrase.	Text	`"cat food"`
`currency`	Currency of the page.	3-letter ISO-4217 currency code.	`"PLN"`
`productTitle`	Product title.	Text	`"Bamboo Blanket - Mint"`
`productId`	Product ID (SKU) in the current context (e.g., product page)	Product SKU (`id` from feed).	`"BAM-SWA-BLA-MIN"`
`categoryPaths`	Filter on the list of category paths.	List of text values consistent with feed (`product_type`).	`["Blankets > Knitted Blankets > Bamboo Blanket"]`
`brand`	Product brand.	Brand consistent with values in the feed (`brand`).	`"Fun with Mum"`
`profiles`	List of profiles assigned to the user for whom the ads are being rendered.	List of text values.	`["premium_client", "sneakers_lover"]`
`adType`	Allows restricting the ad selection to only self-promo or only regular ads.	`ALL`, `AUTOPROMO`, or `SPONSORED`.	`"ALL"`

Additionally, we accept the header Referer, which allows targeting ads based on the URL where the user is located. It is not required to provide the full URL with the domain (but it is allowed): a relative path is sufficient.