> For the complete documentation index, see [llms.txt](https://developers.didomi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.didomi.io/api-and-platform/consents/users/query-user.md). # Query user You can query consent users that belong to your organization calling the [`GET /consents/users`](https://didomi.stoplight.io/docs/didomi-api/64961db3c1b17-retrieve-a-user) endpoint , 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: ```javascript 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: ```javascript 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 ```javascript 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": { ... } } ``` {% hint style="info" %} 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. {% endhint %} ### 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](/api-and-platform/data-manager/regulations.md#regulations-available)). ```javascript GET /consents/users/{organization_user_id} ?organization_id={organization_id} &$by_organization_user_id=true &$merge_users=true ®ulation=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** ```javascript 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: ```json { "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 {% hint style="info" %} The `$include_full_tree` parameter is rate-limited to ensure platform performance. See the Rate limiting documentation for details. {% endhint %} ### Status propagation {% hint style="warning" %} Consents API V2 does not support Status propagation. For Consents API V2, use [One-click consent](/api-and-platform/data-manager/configuration-tree.md#consent-propagation) instead, which provides similar functionality through consent propagation at the purpose level. {% endhint %} 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: ```javascript { "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: ```javascript { "purposes": [ { "id": "purpose-1", "enabled": false, "preferences": [ { "id": "preference-1", "enabled": false } ] } ], "vendors": { ... } } ``` ## --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.didomi.io/api-and-platform/consents/users/query-user.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.