1. Help Center
  2. Compliance report
  3. Advanced Compliance Monitoring

Configuring custom scenarios - API

This article provides further details on setting up a custom scenario using the API.

What is a custom scenario?

By default, Didomi ACM scans run three standard scenarios to help us gather sufficient data for generating a report.

There may be certain cases where our bot's default actions are not compatible with the way your CMP is configured. For example, our bot only searches for the "Refuse" button on the 1st layer of the consent notice. If it does not find this button, the scan is considered to have failed. In order to overcome situations like this (where the bot's expectations do not match the reality) a custom scenario can be configured using the API. 

Configuring a custom scenario

📚 API documentation for interacting with properties (websites to be scanned) is available here.

To configure a property via the API, please have the following information handy:

Label Description Possible values Didomi example
name Name of the report as it appears in the Didomi console string Custom action
website The website to be scanned url starting with https:// https://www.didomi.io/
schedule Cron statement describing how often the report should run

daily: 0 0 * * *

weekly: 0 0 * * 0

monthly: 0 0 1 * *

0 0 1 * *
url Same as website url starting with https:// https://www.didomi.io/
pages Number of pages that  to be scanned int <= 20 10
country Country code from which our bot will access the url

France: fr,

Spain: es,

United States: us,

Canada: ca,

Belgium: be,

Germany: de,

Great Britain: gb

actions -> actions -> params -> selector CSS selector(s) on which the bot should click 

List of CSS selectors (will be clicked on in the same order as inserted).

  • #didomi-notice-learn-more-button,
  • #didomi-consent-popup > div > div > div > div > div.didomi-consent-popup-footer.didomi-popup-footer > div > button.didomi-components-button.didomi-button.didomi-button-standard.standard-button
organisation_id Organisation id of the organisation where the property will be added string demo_org_id

Obtaining the selector

In our example we are trying to get the bot to click on the "Disagree to all" button present on the second layer of the Didomi consent notice. The following steps show how to obtain the CSS selector for doing this: 

  1. Step 1: navigate to the webpage you would like to scan (in our example, didomi.io).
  2. Step 2: right click on the element you would like our bot to click on. Select "Inspect".
  3. Right click on the element <button> and select "Copy" then "Copy selector".
  4. Save this selector (in our case "#didomi-notice-learn-more-button" ) and continue with the steps to obtain the next element to click on. Click on "Configure" in the notice.
  5. Right click on "Disagree to all" and select "Inspect".
  6. Right click on the element <button> and select "Copy" then "Copy selector".
  7. Save this selector (in our case "#didomi-consent-popup > div > div > div > div > div.didomi-consent-popup-footer.didomi-popup-footer > div > button.didomi-components-button.didomi-button.didomi-button-standard.standard-button"). You  can now proceed to customise the API call (steps below).

Creating the API request body

The typical API request has the following format:

  "name": "Custom action",
  "website": "https://www.didomi.io/",
    "scraper": {
        "schedule": "0 0 1 * *",
      "url": "https://www.didomi.io/",
      "pages": 10,
        "country": "fr",
        "enabled": true,
        "actions": [
                "page": "first",
                "actions": [
                        "type": "clickOnElement",
                        "params": {
                            "selector": "#didomi-notice-learn-more-button"
                        "type": "clickOnElement",
                        "params": {
                            "selector": "#didomi-consent-popup > div > div > div > div > div.didomi-consent-popup-footer.didomi-popup-footer > div > button.didomi-components-button.didomi-button.didomi-button-standard.standard-button"
  "organization_id": "demo_org_id"

The elements in bold need to be present inside the JSON for the custom scenario to work. All the other elements should be filled in based on the information from the previous steps. 

Sending the request

Now that the request body has successfully been created, we need to send it to the POST /properties endpoint. Before doing this, we advise you to read the documentation presented here.

❗After adding a property using the API it might take a few hours for the scanning process to be triggered. If your report still has no data after 24 hours please contact your Didomi Account Manager.