Domain delegation

Delegated domains are used in Didomi to:

• load the SDK and send API requests

• load webpage

You delegate a domain that is fully managed by Didomi. All traffic to that domain will be routed directly to Didomi's infrastructure.

You can create domains to load the SDK of your consent notice when your user lands on your website or your single purpose widget to collect preferences about the user to improve his experience.

Using first-party domains reduces reliance on browsers and helps you better capture visitor consent to serve ads that comply with their choices.

	Load the SDK (cmp)	Load as a webpage (preference-center)
Consent notice	✅	❌
Preference widget	✅	✅
Privacy request widget	✅	✅

Schema

Property	Description
id	Fully qualified domain name (e.g. cmp.didomi.io)
usage	What the domain is used for: Load a SDK (cmp) or Load a webpage (preference-center)
type	Type of the domain. custom indicates a domain owned and delegated by a client while managed indicates a domain that Didomi owns and manages like "privacy-center.org". This is automatically set when a domain is created
status	Provisioning status on the Didomi platform. Possible values: draft: domain is created but not deployed yet scheduled: domain is scheduled for deployment to_be_deleted: domain is scheduled for deletion deploying: domain is being provisioned deleting: domain is being deleted failed: domain deployment/deletion failed ready: domain is provisioned and ready for use

Create a domain

Create the DNS record for your domain

If you have multiple websites and intend to use the domain for sharing consents between websites, we recommend picking a sub-domain of your website that has the most traffic.

Before creating a domain in Didomi, ensure it is correctly configured and fully propagated in your DNS provider. Otherwise, domain provisioning will fail.

Create a DNS record with your DNS provider or registrar that manages your domain using the following configuration parameters:

Parameter name	Value	Notes
Name	Your custom domain (privacy.company-name.com or similar)	You will be creating a DNS record for a specific sub-domain of your domain name (like privacy., for instance) and not delegating the DNS management of your whole domain.
Type	NS (Name server)	The type NS allows us to generate SSL certificates for the sub-domain and serve your privacy center with SSL/HTTPS.
TTL (seconds)	300
Value	To load a SDK ns1.privacy-center.org ns2.privacy-center.org ns3.privacy-center.org ns4.privacy-center.org To load a Webpage ns1.preference-center.org ns2.preference-center.org ns3.preference-center.org ns4.preference-center.org	Didomi's name servers that will host the DNS records for your custom domain

If you need help with this step, feel free to reach out to [email protected] and we'll be happy to help.

If you are using CloudFront from Amazon Web Services

To support your custom domain, we will create a dedicated CloudFront distribution with your custom domain as a CNAME. Because of AWS restrictions, it is not possible for us to create that distribution if you already have a distribution in your account with either the exact same CNAME or a matching wildcard CNAME.

For instance, if you have chosen to use the custom domain privacy.company.com and already have a CloudFront distribution with either privacy.company.com or *.company.com as CNAMEs, we will not be able to host the custom domain for you.

Create a domain

You can create a domain by sending a POST request to the /domain endpoint.

To do so, you must provide:

• id: the domain name

• usage: the intended usage of the domain

• organization_id: the ID of the organization

• status: set to scheduled to trigger provisioning

POST https://api.didomi.io/domains

{
  "id": "YOUR_DOMAIN_NAME",
  "usage": "cmp",
  "status": "scheduled",
  "organization_id": "YOUR_ORGANIZATION_ID"
}

Once your domain is created and marked as ready, refer to these documentations to use it in your consent notice or in your preference/privacy request widgets.

Retry a failed domain

If domain provisioning fails, the domain status will be set to failed. To retry:

1. Ensure the DNS records are correctly configured and fully propagated.

2. Delete the failed domain.

3. Create the domain again using the same information.

List the domains

You can list the domains of your organization by sending a GET request to the /domain endpoint.

GET https://api.didomi.io/domains

RESPONSE

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "YOUR_DOMAIN_NAME",
      "organization_id": "YOUR_ORGANIZATION_ID",
      "description": "My Preference Center",
      "enabled": true,
      "status": "ready",
      "type": "managed",
      "usage": "preference-center",
      "widget_id": "YOUR_ENTITY_ID", // Deprecated
      "entity_id": "YOUR_ENTITY_ID",
      "error": null,
      "created_at": "2025-06-04T19:23:20.849Z",
      "updated_at": "2025-06-04T19:23:20.849Z",
      "version": 0
    },

You can list a specific domain by sending a GET request to the /domains/{id} endpoint.

Once your domain is created and marked as ready, refer to these documentations to use it in your consent notice or in your preference/privacy request widgets.

Delete a domain

You can delete a domain by sending a PATCH request to the /domains/{id} endpoint and setting the status to to_be_deleted.

If the entity_id is not null and contains a widget ID, you must first unassign the domain from the widget before you can delete the domain.

PATCH https://api.didomi.io/domains/id

{
  "status": "to_be_deleted"
}