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

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

While you can specify a 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.

Example

POST /consents/users?organization_id={organization_id}
BODY
{
"organization_user_id": "user@domain.com",
"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.

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.

Paginate through users

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_id={organization_id}&organization_user_id={organization_user_id}
RESPONSE
{
"data": [
{
"id": "0cc784a0-4425-45ca-a62f-00dd588d1526",
"organization_user_id": "organization_user_id",
"consents": {
...
}
}
],
"limit": 100,
"cursor": null
}

User Schema

Users have the following schema:

{
/**
* The Didomi user ID
* A random UUID for users encountered on websites and an IDFA/ADID for
* users from 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 user 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,
/**
* Consent status of the user
*/
consents: {
/**
* Purposes that the user has made choices for
*/
purposes: [
{
/**
* Unique purpose ID
*/
id: 'string',
/**
* Whether the user has given consent to this purpose or not
*/
enabled: boolean,
/**
* Extra preferences expressed for the purpose
*/
preferences: [
{
/**
* Unique preference ID
*/
id: 'string',
/**
* Whether the user has enabled this preference or not
*/
enabled: boolean,
/**
* Channels
*/
channels: [
{
/**
* Unique channel ID
*/
id: 'string',
/**
* Whether the user has enabled this channel or not
*/
enabled: boolean,
}
],
/**
* Free-form metadata object on the preference
*/
metadata: Object,
}
]
},
...
],
/**
* 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', ...]
}
}
}