Users

Consent users represent end users of your applications or websites that Didomi is storing consent and preferences information for.

The User entity represents the latest consent status, for a given regulation, of an end user as well as additional metadata. That's the entity that you should query when you want to check if you have consent for a specific data processing or purpose.

The /consents/users endpoint of the API exposes the users managed by Didomi for your organizations. For a full reference of the endpoint and the resources that it returns, visit https://api.didomi.io/docs/.

Create a consent user

While you can specify the consent status for a user when you create it, we recommend using consent events instead for registering the user consent status as you will benefit from automated consent history and updates. Otherwise it would not be possible.

You can create a user by calling the POST /consents/users endpoint and providing basic information on the user as well as custom metadata that you want to associate with the user.

You can provide following information on users:

• Organization user ID: a free-form user ID that is specific to your organization and that is used to identify the user within your organization. This could be an email address, a CRM ID, etc. It can be used to query users and events.

• Metadata: a free-form object with any custom metadata that you want to associate with the user

• Consents: the consent status of the user for purposes, preferences, channels and vendors for GDPR regulation

Example

POST /consents/users?organization_id={organization_id}

BODY
{
  "organization_user_id": "[email protected]",
  
  "metadata": {
    ... free-form object with user metadata
  }
}

See the API documentation for more details on this endpoint.

Query a consent user

You can query consent users that belong to your organization, and filter by user ID or organization user ID.

Paginate through users

Users are returned by pages of 100 and every query returns a cursor value that can be used to get the next page of results. You can iterate through pages of results by specifying the $cursor query-string parameter from the previous query. The returned cursor is null when there is no more result available.

Get the first 100 users that belong to an organization:

GET /consents/users?organization_id={organization_id}

RESPONSE
{
  "data": [
    ...list of 100 users
  ],
  "limit": 100, // Number of users in the current page
  "cursor": ... // Cursor to use for querying the next page of results
}

Get the following 100 users:

GET /consents/users
  ?organization_id={organization_id}
  &$cursor={cursor from previous query}

RESPONSE
{
  "data": [
    ...list of 100 users
  ],
  "limit": 100, // Number of users in the current page
  "cursor": ... // Cursor to use for querying the next page of results
}

Get a user by its organization user ID

GET /consents/users/{organization_user_id}
  ?organization_id={organization_id}
  &$by_organization_user_id=true
  &$merge_users=true

RESPONSE
{
  "id": "0cc784a0-4425-45ca-a62f-00dd588d1526",
  "organization_user_id": "organization_user_id",
  "consents": {
    ...
  }
}

The $merge_users query parameter aggregates the consent records of users with the same organizationUserId into a single object, providing a consolidated view of their unified consent status.

Get user's consent state for a given regulation

By default, user choices are registered under GDPR regulation.

For organizations managing users globally under various privacy laws, you can query the user's consent state for specific regulations by specifying it in the query-string parameter regulation (See all regulations supported by Didomi).

GET /consents/users/{organization_user_id}
  ?organization_id={organization_id}
  &$by_organization_user_id=true
  &$merge_users=true
  &regulation=cpra

RESPONSE
{
  "id": "0cc784a0-4425-45ca-a62f-00dd588d1526",
  "organization_user_id": "organization_user_id",
  "consents": {
    ...
  }
}

Include full configuration tree

The $include_full_tree query-string parameter provides enhanced functionality for building comprehensive user interfaces and analytics. When set to true, this parameter returns a complete representation of your organization's configuration tree merged with user consent data.

What this parameter provides

When $include_full_tree=true is included in your request:

• Complete tree coverage: All purposes, preferences, and values from your configuration tree are included, even those for which the user hasn't made choices

• Content information: Names and descriptions are included for purposes, preferences, and values when available from the configuration tree

• Full value representation: The all_values property shows both checked and unchecked values, enabling complete reconstruction of the consent configuration

• Hierarchical structure: Parent-child relationships are maintained through the parent_id property

• Tree metadata: The config_tree property indicates which configuration tree was used

Example request

GET /consents/users/{organization_user_id}
  ?organization_id={organization_id}
  &$by_organization_user_id=true
  &$include_full_tree=true

Enhanced response structure

With $include_full_tree=true, the response includes additional properties:

{
  "consents": {
    "config_tree": {
      "id": "iKgQKKDC",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    },
    "purposes": [
      {
        "id": "NQYyDFPt",
        "from_tree": true,
        "enabled": false,
        "name": {
          "en": "Communicate with you",
          "fr": "Communiquer avec vous"
        },
        "description": {
          "en": "We use your email address to communicate with you about your account and to send you marketing communications.",
          "fr": "Nous utilisons votre adresse électronique pour communiquer avec vous à propos de votre compte et pour vous envoyer des communications marketing."
        },
        "values": {
          "jbNcY6PY": {
            "from_tree": true,
            "parent_id": null,
            "value": "UXgyk38m,9xMz479d",
            "name": {
              "en": "Email communications",
              "fr": "Communications par email"
            },
            "description": {
              "en": "Receive email updates about your account and marketing offers",
              "fr": "Recevoir des mises à jour par email sur votre compte et des offres marketing"
            },
            "all_values": {
              "UXgyk38m": {
                "from_tree": true,
                "name": {
                  "en": "Newsletter",
                  "fr": "Newsletter"
                },
              },
              "9xMz479d": {
                "from_tree": false
              },
              "wVpwFXMK": {
                "from_tree": true,
                "name": {
                  "en": "Special offers",
                  "fr": "Offres spéciales"
                },
                "description": {
                  "en": "Exclusive promotions and discounts",
                  "fr": "Promotions et réductions exclusives"
                }
              }
            }
          },
          "gH5dc4Ed": {
             "from_tree": true,
            "parent_id": "UXgyk38m",
            "value": "",
            "name": {
              "en": "Sports",
              "fr": "Sports"
            },
            "description": {
              "en": "Sports",
              "fr": "Sports"
            },
            "all_values": {
              "hg4lHb1q": {
                "from_tree": true,
                "name": {
                  "en": "Soccer",
                  "fr": "Soccer"
                }
              },
              "n5Ergcrq": {
                "from_tree": true,
                "name": {
                  "en": "Tennis",
                  "fr": "Tennis"
                }
              }
            } 
          }
        }
      }
    ]
  }
}

Key properties explained

• from_tree: Indicates whether an item exists in your configuration tree (true) or was added from user consent data (false)

• parent_id: Establishes parent-child relationships between items, allowing reconstruction of the nested hierarchy

• all_values: Contains both checked and unchecked values, providing complete visibility into the consent configuration

• config_tree: Metadata about the configuration tree used to build the response

The $include_full_tree parameter is rate-limited to ensure platform performance. See the Rate limiting documentation for details.

Status propagation

Consents API V2 does not support Status propagation. For Consents API V2, use One-click consent instead, which provides similar functionality through consent propagation at the purpose level.

Status propagation is a feature available in Consents API V1 (deprecated), where the user choice at a specific level automatically propagates to elements at the lower level.

For instance, if a user sets enabled to false at the purpose level, it overrides lower-level enabled values (for preferences and channels) that will also be set to false automatically.

A practical example is that enabled at the purpose level can be used to implement Subscribe to all / Unsubscribe to all features where a user can subscribe to / unsubscribe from all preferences (current and future) by setting enabled to false on the purpose. Future preferences under that purpose will automatically get enabled set to false.

For instance, if you are pushing the following consent status to the API:

{
  "purposes": [
    {
      "id": "purpose-1",
      "enabled": false,
      "preferences": [
        {
          "id": "preference-1",
          "enabled": true
        }
      ]
    }
  ],
  
  "vendors": { ... }
}

This status from the event indicates that the user has disabled the purpose but enabled the preference. When updating the user status from the event, the status from the purpose will be propagated down to the preference and the API will store:

{
  "purposes": [
    {
      "id": "purpose-1",
      "enabled": false,
      "preferences": [
        {
          "id": "preference-1",
          "enabled": false
        }
      ]
    }
  ],
  
  "vendors": { ... }
}

Disable integrations

If you are importing users already present in your systems and there is no need for these users to be forwarded to your integrations, you can add the query parameter $disable_integrations=true to your request to disable such forwarding.

One-click consent and user consent status

When one-click consent is enabled for a selected purpose in your Configuration Tree, preference values that were automatically set by propagation appear in the user consent status the same way as values explicitly set by the user.

The user consent status returned by the GET /consents/users endpoint does not include the propagation or from_propagation flags. These flags are only present in events (accessible via the /consents/events endpoint) to maintain the history of how values were set.

This means:

• User consent status shows the final result after propagation is applied

• Both propagated and explicitly set values appear the same way in the user consent status

• To determine if a value was set by propagation, you must query the consent events history

For more information about one-click consent, see the Configuration Tree documentation and Events documentation.

User Schema

Users have the following schema:

If you subscribed to Didomi after the 18th of January 2022, you are using the Consents API V2.

Consents API V2

{
    /**
     * The Didomi user ID
     * A random UUID generated by the SDK on websites and mobile apps.
     */
    id: 'string',
    
    /**
     * A unique user ID in your organization
     * This could be an email, a phone number, an internal client ID, etc.
     * It is used to link Didomi users to your internal systems.
     * Multiple Didomi users can be associated with one organization ID.
     */
    organization_user_id: 'string',
    
    /**
     * Version number of the user record
     * User for optimistic locking
     */
    version: Number,
    
    /**
     * Creation date of the user record
     */
    created_at: 'ISO8601 date',
    
    /**
     * Last update date of the user record
     */
    updated_at: 'ISO8601 date',
    
    /**
     * Free-form metadata object on the user
     */
    metadata: Object,
    
    /**
     * Two-letter ISO code of the user's country.
     * `null` if no value is provided. This property is never set automatically by Didomi.
     */
    country: 'string',

    /**
     * Two-letter ISO country code of the last consent event for the user.
     * The country of a consent event might differ from the initial
     * user's country. This property stores the last seen country from
     * the user's consent events.
     * Auto-filled for Didomi SDK events.
     */
    last_seen_country: 'string',
    
    /**
     * Consent status of the user
     */
    consents: { 
        /**
         * Purposes that the user has made choices for
         * By default, consent state is applied to GDPR
         */
         
        /**
         * Configuration tree metadata (only present when $include_full_tree=true)
         */
        config_tree?: {
            /**
             * Unique ID of the config tree
             */
            id: string,
            
            /**
             * Creation date of the config tree
             */
            created_at: 'ISO8601 date',
            
            /**
             * Last update date of the config tree
             */
            updated_at: 'ISO8601 date,
        },
        
        purposes: [
            {
                /**
                 * Unique purpose ID
                 */
                id: "string", 
                
                metadata: Object, 
                
                /**
                 * Whether the user has given consent to this purpose or not
                 * A null value indicates that the user has made choices for
                 * preferences values
                 */                
                enabled: boolean || null, 
                                
                /**
                 * Indicates whether this purpose exists in the configuration tree (only present when $include_full_tree=true)
                 */
                from_tree?: boolean,
                
                /**
                 * Name of the purpose in different languages (only present when $include_full_tree=true and available)
                 */
                name?: {
                    [LANGUAGE_CODE: string]: string,
                },
                
                /**
                 * Description of the purpose in different languages (only present when $include_full_tree=true and available)
                 */
                description?: {
                    [LANGUAGE_CODE: string]: string,
                },
                
                /**
                 * Preferences that the user has made choices for
                 */                  
                values: {
                    [PREFERENCE_ID]: {
                        /**
                        * Preference values that the user has made positive choices for
                        * An empty string indicates that the user has made a negative 
                        * choice for the preference
                        */ 
                        value: "PREF_VALUE_ID_1,PREF_VALUE_ID_2",
                                                
                        /**
                         * Indicates whether this preference exists in the configuration tree (only present when $include_full_tree=true)
                         */
                        from_tree?: boolean,

                        /**
                         * The ID of the parent entity; set to null if this is a root-level item with no parent (only present when $include_full_tree=true)
                         */
                        parent_id?: string | null,
                        
                        /**
                         * Name of the preference in different languages (only present when $include_full_tree=true and available)
                         */
                        name?: {
                            [LANGUAGE_CODE: string]: string,
                        },
                        
                        /**
                         * Description of the preference in different languages (only present when $include_full_tree=true and available)
                         */
                        description?: {
                            [LANGUAGE_CODE: string]: string,
                        },
                        
                        /**
                         * All values for this preference, including unchecked ones (only present when $include_full_tree=true)
                         */
                        all_values?: {
                            [VALUE_ID]: {
                                /**
                                 * Indicates whether this value exists in the configuration tree
                                 */
                                from_tree: boolean,
                                
                                /**
                                 * Name of the value in different languages (only present when available)
                                 */
                                name?: {
                                    [LANGUAGE_CODE: string]: string,
                                },
                            },
                        },
                    }
                }
            }
            ...
        ],

        /**
         * Vendors that the user has made choices for
         */
        vendors: {
            /**
             * List of vendor IDs that the user has given consent to
             */
            enabled: ['string', ...],
            
            /**
             * List of vendor IDs that the user has denied consent to
             */
            disabled: ['string', ...]
        },
        
        /**
         * TCF consent string for the user
         * (if it was available or generated at the time of consent collection)
         */
        tcfcs: 'string'
    }
}

Consents API V1 (Deprecated)