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), 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

📘

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

API reference: https://developer-onetrust-com.ezp-prod1.hul.harvard.edu/onetrust/reference/createdomaingroupusingpost

Create a domain group by leveraging this API:

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

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

📘

When specifying URLs under the urls key, use the hostname format. You can retrieve it using window.location.hostname.

Credentials

Set up your client credentials under Settings > Client credentials. For scope, ensure all the ‘Cookie’
scopes are selected (COOKIE, COOKIE_FREE, COOKIE_READ).

Sample cURL

curl --location 'https://app-onetrust-com.ezp-prod1.hul.harvard.edu/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

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 --location 'https://cookies-data.onetrust.io/bannersdk/v1/domaingroupcheck' \
--header 'location: cdn.cookielaw.org' \
--header 'domainId: abcdefg123-hijk-45lm-nop274e89017d20f70' \
--header 'url: dataguidance.com'

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.ezp-prod1.hul.harvard.edu/onetrust/reference/createdomaingroupusingpost

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

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

📘

When specifying URLs under the urls key, use the hostname format. You can retrieve it using window.location.hostname.

Credentials

Set up your client credentials under Settings > Client credentials. For scope, ensure all the ‘Cookie’
scopes are selected (COOKIE, COOKIE_FREE, COOKIE_READ).

Sample cURL

curl --location 'https://app-onetrust-com.ezp-prod1.hul.harvard.edu/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 to validate the new addition.

Remove All Domains from an Existing Domain Group

API reference: https://developer-onetrust-com.ezp-prod1.hul.harvard.edu/onetrust/reference/createdomaingroupusingpost

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

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

Credentials

Set up your client credentials under Settings > Client credentials. For scope, ensure all the ‘Cookie’
scopes are selected (COOKIE, COOKIE_FREE, COOKIE_READ).

Sample cURL

curl --location 'https://app-onetrust-com.ezp-prod1.hul.harvard.edu/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 to validate the successful removal.

📘

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.