# Custom actions via API

{% hint style="info" %}
**Premium Feature**: Advanced Compliance Monitoring
{% endhint %}

Custom actions allow your organization to customize the behavior of the Didomi bot as it interacts with your consent notice and/or domain when scanning for a compliance report. In this article, we will cover how to leverage the Didomi API to configure custom actions in your organization's compliance report.

### Resources

Before continuing with this article we recommend that your organization familiarizes itself with how to interact with the Didomi API. Refer to the resources below for more information:

* [Introduction to Didomi API](https://developers.didomi.io/api-and-platform/introduction)
* [Didomi API specification](https://didomi.stoplight.io/docs/didomi-api/4ac4424b6d533-create-one-or-many-properties)

### Use cases

There are two primary use cases to configure custom actions for the Didomi bot that scans your website:

<table><thead><tr><th width="295">Use case</th><th>Description</th></tr></thead><tbody><tr><td><a href="#custom-scenario">Custom scenario</a></td><td>Customize the Didomi bot behavior when navigating a consent notice that is not compatible with the default actions of the bot</td></tr><tr><td><a href="#accessing-a-logged-in-environment">Accessing a logged in environment</a></td><td>Customize the Didomi bot behavior when providing credentials is a multi-step process in the authentication process </td></tr></tbody></table>

### Configure custom action API request&#x20;

In this section, we will cover how to configure custom actions using the Didomi API for specific use cases and illustrate the process using an example.&#x20;

{% tabs %}
{% tab title="Custom scenario" %}
{% hint style="info" %}
Alternatively, custom scenarios for the Didomi bot can be configured directly from the Didomi console. [Click here](/advanced-compliance-monitoring-acm/compliance-report-acm/customize-bot-scenario.md) to learn more.
{% endhint %}

By default, Advanced Compliance Monitoring scans for three standard scenarios (Accept all, Refuse all, and No actions) to gather sufficient data to generate the compliance report.&#x20;

It can be the case that the Didomi bot used for scanning fails because the default behavior of the bot for the respective scenarios does not align with how your CMP is configured. In this tab, we will cover how to customize the bot behavior for a scenario via API.&#x20;

* [Example](#example)
* [Retrieve CSS selector(s)](#retrieve-css-selector-s)
* [API request](#api-request)

***

#### Example

In the example used in the API request below we are scanning a consent notice where the action to refuse all purposes and vendors is only present on the second layer of the consent notice. However, the default behavior of the Didomi bot is to only search for this action on the first layer of the consent notice and since it will not find this button to do, the scan for that scenario will fail.&#x20;

The custom action via API will customize the **Refuse all** scenario behavior for the Didomi bot so that it navigates to the second layer of the consent notice where the button to refuse all purposes and vendors is present.

#### Retrieve CSS selector(s)

CSS selector values instruct the Didomi bot where to click (or insert text) to navigate through your consent notice. To collect the CSS selector values:

1. Navigate to your website and load your consent notice
2. Right-click the desired element on the consent notice where the Didomi bot should click (or insert text)
3. Select **Inspect** from the subsequent menu

<figure><img src="/files/RKy2Le7k8Adh6gWHkIxe" alt="" width="375"><figcaption></figcaption></figure>

The element should be highlighted in the Inspector. Right-click the highlighted item in the Inspector and select **Copy > Copy selector** (or **CSS Selector** depending on browser).

<figure><img src="/files/hMLKWiAx3eWaO6sgvSFd" alt="" width="563"><figcaption></figcaption></figure>

Repeat as necessary for elements that the Didomi bot will need to click in order to achieve the desired behavior.

For our custom Refuse all scenario, the Didomi bot will need to click the *Learn More* button on the first layer of the consent notice and then click the *Disagree to all* button on the second layer of the consent notice.&#x20;

#### API request

In this section, we will cover how to construct the API request to customize the **Refuse all** scenario.

{% hint style="info" %}
Didomi strongly encourages you to visit the [API specification for creating a new property ](https://didomi.stoplight.io/docs/didomi-api/4ac4424b6d533-create-one-or-many-properties)for the compliance report for all parameters available in the request. Additionally, ensure that your request also has the required [bearer token](https://developers.didomi.io/api-and-platform/introduction/authentication) in the Authorization header.
{% endhint %}

**Endpoint**

Your API request should be made to the following endpoint:

<table data-header-hidden><thead><tr><th></th><th width="530"></th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Method</strong></td><td>POST</td><td></td></tr><tr><td><strong>URL</strong></td><td><a href="https://api.didomi.io/v1/reports/compliances/properties">https://api.didomi.io/v1/reports/compliances/properties</a></td><td></td></tr><tr><td><strong>Query Parameter</strong></td><td>organization_id</td><td></td></tr></tbody></table>

**Body**

When constructing the body of the API request, the custom scenario configuration is performed in  `scenarios[].scenario_actions` for the respective scenario being customized. Add an object to `scenarios[].scenario_actions` for each step the Didomi bot should perform to execute the desired behavior.&#x20;

For our custom **Refuse all** scenario, the Didomi bot should first click the *Learn More* button (identified by the CSS selector) and then the *Disagree to all* button (identified by the CSS selector). See line 20-35 in the example below.

<pre class="language-json" data-line-numbers data-expandable="true"><code class="lang-json">{
  "name": "Custom Action API",
  "website": "https://demosite.com",
  "scenarios": [
    {
      "enabled": true,
      "type": "accept_all",
      "scenario_actions": [
        {
          "type": "accept",
          "order": 0
        }
      ]
    },
    {
      "enabled": true,
      "type": "no_actions",
      "scenario_actions": []
    },
<strong>    {
</strong><strong>      "enabled": true,
</strong><strong>      "type": "refuse_all",
</strong><strong>      "scenario_actions": [
</strong><strong>        {
</strong><strong>          "type": "click",
</strong><strong>          "order": 0,
</strong><strong>          "css_selector": "#didomi-notice-learn-more-button"
</strong><strong>        },
</strong><strong>        {
</strong><strong>          "type": "click",
</strong><strong>          "order": 1,
</strong><strong>          "css_selector": "#btn-toggle-disagree"
</strong><strong>        }        
</strong><strong>      ]
</strong><strong>    }
</strong>  ],
  "enabled": true,
  "pages_count": 150,
  "country": "fr",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}
</code></pre>

{% endtab %}

{% tab title="Accessing a logged in environment" %}
{% hint style="info" %}
If the login form for your website is a single page that includes a username, password, and submit button, your organization can alternatively use the Didomi console to configure a scan for a domain that requires login. [Click here](/advanced-compliance-monitoring-acm/compliance-report-acm/scan-domain-that-requires-login.md) for more information.
{% endhint %}

In this tab, we will cover how to customize the Didomi bot behavior via API so that it can successfully navigate the way your login form is configured for a domain.

* [Example](#example-1)
* [Retrieve CSS selector(s)](#retrieve-css-selector-s-1)
* [API request](#api-request)

***

#### Example

In the example used in the API request below, the domain for which we are configuring a compliance report for has a login form where the user first submits their email address and then submits their password.

#### Retrieve CSS selector(s)

CSS selector values instruct the Didomi bot where to click (or insert text) in the login form. To collect the CSS selector values:

1. Navigate to the login form
2. Right-click the desired element of where the Didomi bot should click (or insert text)
3. Select **Inspect** from the subsequent menu

<figure><img src="/files/KWOeBLzC0tpASb884lvT" alt="" width="375"><figcaption></figcaption></figure>

The element should be highlighted in the Inspector. Right-click the highlighted item in the Inspector and select **Copy > Copy selector** (or **CSS Selector** depending on browser).

<figure><img src="/files/AsS9FYjNnqJ8yXbaIQdV" alt="" width="563"><figcaption></figcaption></figure>

Repeat the above steps to retrieve the CSS selectors for the user name field, password field, and the submit button.

#### API request

In this section, we will cover how to construct the API request to customize how the Didomi bot navigates the login form

{% hint style="info" %}
Didomi strongly encourages you to visit the [API specification for creating a new property ](https://didomi.stoplight.io/docs/didomi-api/4ac4424b6d533-create-one-or-many-properties)for the compliance report for all parameters available in the request. Additionally, ensure that your request also has the required [bearer token](https://developers.didomi.io/api-and-platform/introduction/authentication) in the Authorization header.
{% endhint %}

**Endpoint**

Your API request should be made to the following endpoint:

<table data-header-hidden><thead><tr><th></th><th width="530"></th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Method</strong></td><td>POST</td><td></td></tr><tr><td><strong>URL</strong></td><td><a href="https://api.didomi.io/v1/reports/compliances/properties">https://api.didomi.io/v1/reports/compliances/properties</a></td><td></td></tr><tr><td><strong>Query Parameter</strong></td><td>organization_id</td><td></td></tr></tbody></table>

**Body**

When constructing the body of the API request, the custom login action is configured in the `login` object.

the custom scenario configuration is performed in  `scenarios[].scenario_actions` for the respective scenario being customized. Add an object to `scenarios[].scenario_actions` for each step the Didomi bot should perform to execute the desired behavior.&#x20;

sdfasdf
{% endtab %}
{% endtabs %}

1. Proceed the same when prompted for the password. Collect the imput selector for the password field.\
   ![](https://support.didomi.io/hs-fs/hubfs/image-png-Mar-05-2024-11-09-34-5302-AM.png?width=650\&height=1872\&name=image-png-Mar-05-2024-11-09-34-5302-AM.png)\
   ![](https://support.didomi.io/hs-fs/hubfs/image-png-Mar-05-2024-11-10-12-1147-AM.png?width=650\&height=1550\&name=image-png-Mar-05-2024-11-10-12-1147-AM.png)
2. Collect the css selector for the submit (continue) button. \
   ![](https://support.didomi.io/hs-fs/hubfs/image-png-Mar-05-2024-11-11-35-4658-AM.png?width=652\&height=1565\&name=image-png-Mar-05-2024-11-11-35-4658-AM.png)\
   ![](https://support.didomi.io/hs-fs/hubfs/image-png-Mar-05-2024-11-12-10-8774-AM.png?width=651\&height=1535\&name=image-png-Mar-05-2024-11-12-10-8774-AM.png)

**Creating the API Request body**

The typical API request has the following format:

<pre><code>{
    "name": "Custom action - login",
    "website": "https://console.didomi.io/",
    "scraper": {
        "schedule": "0 0 1 * *",
        "url": "https://console.didomi.io/",
        "pages": 10,
        "country": "fr",
<strong>        "enabled": true,
</strong>        "actions": [
            {
<strong>                "page": "first",
</strong>                "actions": [
                    {
<strong>                        "type": "type",
</strong>                        "params": {
                            "text":"&#x3C;username>",
                            "selector": "#username"
                        }
                    },
                    {
<strong>                        "type": "clickOnElement",
</strong>                        "params": {
                            "selector": "#submit-button"
                        }
                    },
                    {
<strong>                        "type": "type",
</strong>                        "params": {
                            "text":"&#x3C;password>",
                            "selector": "#Password"
                        }
                    },
                    {
<strong>                        "type": "clickOnElement",
</strong>                        "params": {
                            "selector": "#submit-button"
                        }
                    }
                ]
            }
        ],
<strong>        "scenarios":["NO_USER_CHOICE","CONSENT_TO_ALL","REFUSE_TO_ALL"]
</strong>    },
    "organization_id": "demo_org_id"
}
</code></pre>

The elements in **bold** are all the steps required for the login to be performed. These actions will be done after the interaction of the bot with the notice. In case the notice is displayed after the login is performed we recommend you continue to add as custom scenario the interaction with the notice (see example 1).&#x20;

#### 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.](https://developers.didomi.io/api/introduction)

❗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.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.didomi.io/advanced-compliance-monitoring-acm/compliance-report-acm/custom-actions-via-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.