---
updatedAt: 2026-06-29T18:25:14.000Z
agentTools:
  projectIndex: https://developer.onetrust.com/onetrust/llms.txt
---

# Bulk Domain Management

# What is Bulk Domain Management?

Bulk Domain Management enables you to deploy a single script across multiple domains by organizing them into a domain group. A domain group is a set of domains that share the same primary script. This script operates across all domains in the group and handles consent individually and separately for each domain.

Domain groups are ideal for businesses managing a large number of domain properties that share the same or similar tracking technology templates. As the number of domains grows, maintaining individual scripts and coordinating across teams can become complex. Bulk Domain Management simplifies this by allowing you to associate multiple domains with a single script, streamlining deployment and making updates easier to manage across all domains.

## Key Points to Consider

* This feature is not compatible with Download to Local
* When adding domains to a domain group, use the hostname format. If your website includes subdomains in the hostname (e.g., [www.onetrust.com](http://www.onetrust.com)), each subdomain must be added individually to the domain group. While the same script can be deployed across all subdomains, consent will be stored separately for each one. In this instance, OneTrust recommends managing the domain outside of a domain group. You can scan the root domain as a standalone site within your OneTrust tenant and implement the unique script generated for it. This approach allows consent to persist across all associated subdomains.
* The domain designated as the parent of a domain group must be scanned within the OneTrust tenant. Because the script is tied specifically to the parent domain, the cookie list will only reflect cookies identified from the parent domain
* If a cookie list is displayed in the preference center, it will be populated based on the parent domain’s scan results
* When using Auto-Blocking, only sources detected in the parent domain’s scan will be considered
* Templates and geolocation rules are inherited from the parent domain. Custom branding at the individual domain level is not supported
* Dashboard metrics for all domains in the group are aggregated and shown under the parent domain
* To remove a domain from the group and manage it independently, scan it as a separate site within the OneTrust environment and implement it accordingly

# Setting Up Bulk Domain Management

To set up bulk domains, follow the steps below:

## 1. Create a Domain Group

<Callout icon="📘" theme="info">
  ###

  If you haven't already, scan your parent domain in the OneTrust tenant and publish the associated production script data.
</Callout>

> API reference: <https://developer.onetrust.com/onetrust/reference/createdomaingroupusingpost>

**Create a domain group by leveraging this API:**

```
(POST) https://{tenantURL}/api/cookiemanager/v1/domains/{domainId}/domaingroup
```

| Path Paramaters | Description                                                                       |
| :-------------- | :-------------------------------------------------------------------------------- |
| {tenantURL}     | Domain of your OneTrust tenant (e.g. app.onetrust.com, app-uk.onetrust.com, etc.) |
| {domainId}      | Domain ID of your parent domain's production script (don't add '-test')           |

| Body Parameters  | Description                                                                                                                                                                                                                          |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `removeExisting` | Boolean. Flag to add or remove domains from an existing group. Passing `false` instructs the API to append the incoming URL to an existing group. Passing `true` instructs the API to remove the incoming URL from an existing group |
| `urls`           | A list of URLs to be added to the group                                                                                                                                                                                              |

> To create a net new domain group, set `removeExisting` to `true`.

<Callout icon="📘" theme="info">
  ###

  When specifying URLs under the `urls` key, use the hostname format. You can retrieve it using `window.location.hostname`.
</Callout>

**Credentials**

Set up your client credentials under your tenant's Global Settings > Client credentials. For scope, ensure all the ‘Cookie’<br />scopes are selected (COOKIE, COOKIE\_FREE, COOKIE\_READ).

**Sample cURL**

```curl
curl --location 'https://app.onetrust.com/api/cookiemanager/v1/domains/abcdefg123-hijk-45lm-nop274e89017d20f70/domaingroup' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
  "urls": [
    "onetrust.com",
    "dataguidance.com"
  ],
  "removeExisting": true
}'
```

After successfully running the API, republish your parent domain's production script data from the OneTrust tenant.

## 2. Validate Domain Group Creation

After executing the API in Step 1, confirm that the domain group and all associated URLs have been successfully created. Before proceeding, ensure the production data for the parent domain has been republished.

There are two validation checks:

1. Confirm that all expected URLs are returned by the API below. You can also run the URL in a browser.

```
(GET) https://{cdnLocation}/consent/{domainId}/domain-list.json
```

| Path Paramaters | Description                                                                                |
| :-------------- | :----------------------------------------------------------------------------------------- |
| {cdnLocation}   | CDN location (e.g. cdn.cookielaw\.org, cdn-ukwest.onetrust.com, cdn-au.onetrust.com, etc.) |
| {domainId}      | Domain ID of your parent domain's production script (don't add '-test')                    |

2. Verify that the API response below includes `isValid: true`, indicating that the child domain has been successfully added. Run this check for each child domain in scope.

```curl
curl --location 'https://cookies-data.onetrust.io/bannersdk/v1/domaingroupcheck' \
--header 'location: cdn.cookielaw.org' \
--header 'domainId: abcdefg123-hijk-45lm-nop274e89017d20f70' \
--header 'url: dataguidance.com'
```

| Header   | Description                                                             |
| :------- | :---------------------------------------------------------------------- |
| location | CDN location                                                            |
| domainId | Domain ID of your parent domain's production script (don't add '-test') |
| url      | Child domain to check                                                   |

## 3. Deploy the Script and Validate Functionality

Deploy the script associated with the parent domain across all domains in the domain group.

Verify that the `OptanonConsent` cookie is correctly written to the domain you’re currently visiting. When navigating between different websites within the same domain group (using the shared parent domain script), the consent banner should reappear. This is expected, as consent is stored on a per-domain basis and is not persisted across domains.

# Adding Additional Domains to an Existing Domain Group

> API reference: <https://developer.onetrust.com/onetrust/reference/createdomaingroupusingpost>

**Add domains to an existing domain group by leveraging this API:**

```
(POST) https://{tenantURL}/api/cookiemanager/v1/domains/{domainId}/domaingroup
```

| Path Paramaters | Description                                                                       |
| :-------------- | :-------------------------------------------------------------------------------- |
| {tenantURL}     | Domain of your OneTrust tenant (e.g. app.onetrust.com, app-uk.onetrust.com, etc.) |
| {domainId}      | Domain ID of your parent domain's production script (don't add '-test')           |

| Body Parameters  | Description                                                                                                                                      |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `removeExisting` | Boolean. Flag to add or remove domains from an existing group. Pass `false` to instruct the API to append the incoming URL to an existing group. |
| `urls`           | A list of URLs to be added to the group                                                                                                          |

<Callout icon="📘" theme="info">
  ###

  When specifying URLs under the `urls` key, use the hostname format. You can retrieve it using `window.location.hostname`.
</Callout>

**Credentials**

Set up your client credentials under your tenant's Global Settings > Client credentials. For scope, ensure all the ‘Cookie’<br />scopes are selected (COOKIE, COOKIE\_FREE, COOKIE\_READ).

**Sample cURL**

```curl
curl --location 'https://app.onetrust.com/api/cookiemanager/v1/domains/abcdefg123-hijk-45lm-nop274e89017d20f70/domaingroup' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
  "urls": [
    "onetrust.com",
    "dataguidance.com"
  ],
  "removeExisting": false
}'
```

After successfully running the API, republish your parent domain's production script data from the OneTrust tenant.

See [Validate Domain Group Creation](https://developer.onetrust.com/onetrust/docs/bulk-domain-management-1#2-validate-domain-group-creation) to validate the new addition.

# Remove All Domains from an Existing Domain Group

> API reference: <https://developer.onetrust.com/onetrust/reference/createdomaingroupusingpost>

**Remove ALL domains from an existing domain group by leveraging this API:**

```
(POST) https://{tenantURL}/api/cookiemanager/v1/domains/{domainId}/domaingroup
```

| Path Paramaters | Description                                                                       |
| :-------------- | :-------------------------------------------------------------------------------- |
| {tenantURL}     | Domain of your OneTrust tenant (e.g. app.onetrust.com, app-uk.onetrust.com, etc.) |
| {domainId}      | Domain ID of your parent domain's production script (don't add '-test')           |

| Body Parameters  | Description                                                                                                                              |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `removeExisting` | Boolean. Flag to add or remove domains from an existing group. Pass `true` to instruct the API to remove ALL URLs from an existing group |

**Credentials**

Set up your client credentials under your tenant's Global Settings > Client credentials. For scope, ensure all the ‘Cookie’<br />scopes are selected (COOKIE, COOKIE\_FREE, COOKIE\_READ).

**Sample cURL**

```curl
curl --location 'https://app.onetrust.com/api/cookiemanager/v1/domains/abcdefg123-hijk-45lm-nop274e89017d20f70/domaingroup' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
  "removeExisting": true
}'
```

After successfully running the API, republish your parent domain's production script data from the OneTrust tenant.

See [Validate Domain Group Creation](https://developer.onetrust.com/onetrust/docs/bulk-domain-management-1#2-validate-domain-group-creation) to validate the successful removal.

<Callout icon="📘" theme="info">
  ###

  Individual URLs cannot be removed from a domain group, only the entire group can be cleared at once. If you need to manage a domain separately from the group, the recommended approach is to scan the domain as a standalone site within your OneTrust tenant and implement the unique script generated for that domain.
</Callout>

<br />

# Sibling pages

* [Web CMP JavaScript Methods](https://developer.onetrust.com/onetrust/docs/javascript-api.md)
* [Web CMP Events Guide](https://developer.onetrust.com/onetrust/docs/javascript-events-guide.md)
* [Custom Geolocation Integration](https://developer.onetrust.com/onetrust/docs/custom-geolocation-integration.md)
* [Display Preference Center on Script Load](https://developer.onetrust.com/onetrust/docs/display-preference-center.md)
* [AMP Integration](https://developer.onetrust.com/onetrust/docs/amp-integration.md)
* [Cookie Consent Support for AMP Websites](https://developer.onetrust.com/onetrust/docs/cookie-consent-support-for-amp-websites.md)
* [Configuring a Content Security Policy with OneTrust CDN](https://developer.onetrust.com/onetrust/docs/content-security-policy-cdn.md)
* [IAB CCPA: Configuring the US Privacy String](https://developer.onetrust.com/onetrust/docs/iab-ccpa-us-privacy-string.md)
* [IAB TCF Developer Guide](https://developer.onetrust.com/onetrust/docs/iab-tcf-developer-guide.md)
* [Using TCF with Header Bidding (TCF Stub)](https://developer.onetrust.com/onetrust/docs/using-tcf-with-header-bidding.md)
* [Using TCF with Prebid](https://developer.onetrust.com/onetrust/docs/using-tcf-with-prebid.md)
* [Single Page Applications](https://developer.onetrust.com/onetrust/docs/single-page-applications.md)
* [Multi-Touch Consent](https://developer.onetrust.com/onetrust/docs/multi-touch-consent.md)
* [Google Consent Mode](https://developer.onetrust.com/onetrust/docs/using-google-consent-mode.md)
* [Custom Common CSS and JavaScript](https://developer.onetrust.com/onetrust/docs/common-custom-css.md)
* [Custom Common HTML](https://developer.onetrust.com/onetrust/docs/custom-common-html.md)
* [Server Side Rendering Performance & Availability](https://developer.onetrust.com/onetrust/docs/server-side-rendering-performance-availability.md)
* [PRA/DSAR - Web CMP Opt Out](https://developer.onetrust.com/onetrust/docs/dsarpra-web-cmp-opt-out.md)
* [Cookie Consent Integration with Google Tag Gateway for Advertisers](https://developer.onetrust.com/onetrust/docs/cookie-consent-integration-with-google-tag-gateway-for-advertisers.md)