Didomi - Developers documentation
Search…
API
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
1
POST /consents/users?organization_id={organization_id}
2
​
3
BODY
4
{
5
"organization_user_id": "[email protected]",
6
7
"metadata": {
8
... free-form object with user metadata
9
}
10
}
Copied!
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:
1
GET /consents/users?organization_id={organization_id}
2
​
3
RESPONSE
4
{
5
"data": [
6
...list of 100 users
7
],
8
"limit": 100, // Number of users in the current page
9
"cursor": ... // Cursor to use for querying the next page of results
10
}
Copied!
Get the following 100 users:
1
GET /consents/users?organization_id={organization_id}&$cursor={cursor from previous query}
2
​
3
RESPONSE
4
{
5
"data": [
6
...list of 100 users
7
],
8
"limit": 100, // Number of users in the current page
9
"cursor": ... // Cursor to use for querying the next page of results
10
}
Copied!
Get a user by its organization user ID
1
GET /consents/users?organization_id={organization_id}&organization_user_id={organization_user_id}
2
​
3
RESPONSE
4
{
5
"data": [
6
{
7
"id": "0cc784a0-4425-45ca-a62f-00dd588d1526",
8
"organization_user_id": "organization_user_id",
9
"consents": {
10
...
11
}
12
}
13
],
14
"limit": 100,
15
"cursor": null
16
}
Copied!
Status propagation
Consents API V2 does not support Status propagation.
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:
1
{
2
"purposes": [
3
{
4
"id": "purpose-1",
5
"enabled": false,
6
"preferences": [
7
{
8
"id": "preference-1",
9
"enabled": true
10
}
11
]
12
}
13
],
14
15
"vendors": { ... }
16
}
Copied!
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:
1
{
2
"purposes": [
3
{
4
"id": "purpose-1",
5
"enabled": false,
6
"preferences": [
7
{
8
"id": "preference-1",
9
"enabled": false
10
}
11
]
12
}
13
],
14
15
"vendors": { ... }
16
}
Copied!
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
Consents API V1 (Deprecated)
1
{
2
/**
3
* The Didomi user ID
4
* A random UUID generated by the SDK on websites and mobile apps.
5
*/
6
id: 'string',
7
8
/**
9
* A unique user ID in your organization
10
* This could be an email, a phone number, an internal client ID, etc.
11
* It is used to link Didomi users to your internal systems.
12
* Multiple Didomi users can be associated with one organization user ID.
13
*/
14
organization_user_id: 'string',
15
16
/**
17
* Version number of the user record
18
* User for optimistic locking
19
*/
20
version: Number,
21
22
/**
23
* Creation date of the user record
24
*/
25
created_at: 'ISO8601 date',
26
27
/**
28
* Last update date of the user record
29
*/
30
updated_at: 'ISO8601 date',
31
32
/**
33
* Free-form metadata object on the user
34
*/
35
metadata: Object,
36
37
/**
38
* Two-letter ISO code of the user's country.
39
* `null` if no value is provided. This property is never set automatically by Didomi.
40
*/
41
country: 'string',
42
​
43
/**
44
* Two-letter ISO country code of the last consent event for the user.
45
* The country of a consent event might differ from the initial
46
* user's country. This property stores the last seen country from
47
* the user's consent events.
48
* Auto-filled for Didomi SDK events.
49
*/
50
last_seen_country: 'string',
51
52
/**
53
* Consent status of the user
54
*/
55
consents: {
56
/**
57
* Purposes that the user has made choices for
58
*/
59
purposes: [
60
{
61
/**
62
* Unique purpose ID
63
*/
64
id: "string",
65
66
metadata: Object,
67
68
/**
69
* Whether the user has given consent to this purpose or not
70
* A null value indicates that the user has made choices for
71
* preferences values
72
*/
73
enabled: boolean || null,
74
75
/**
76
* Preferences that the user has made choices for
77
*/
78
values: {
79
[PREFERENCE_ID]: {
80
/**
81
* Preference values that the user has made positive choices for
82
* An empty string indicates that the user has made a negative
83
* choice for the preference
84
*/
85
value: "PREF_VALUE_ID_1,PREF_VALUE_ID_2"
86
}
87
}
88
}
89
...
90
],
91
​
92
/**
93
* Vendors that the user has made choices for
94
*/
95
vendors: {
96
/**
97
* List of vendor IDs that the user has given consent to
98
*/
99
enabled: ['string', ...],
100
101
/**
102
* List of vendor IDs that the user has denied consent to
103
*/
104
disabled: ['string', ...]
105
},
106
107
/**
108
* TCF consent string for the user
109
* (if it was available or generated at the time of consent collection)
110
*/
111
tcfcs: 'string'
112
}
113
}
Copied!
1
{
2
/**
3
* The Didomi user ID
4
* A random UUID generated by the SDK on wbsites and mobile apps.
5
*/
6
id: 'string',
7
8
/**
9
* A unique user ID in your organization
10
* This could be an email, a phone number, an internal client ID, etc.
11
* It is used to link Didomi users to your internal systems.
12
* Multiple Didomi users can be associated with one organization user ID.
13
*/
14
organization_user_id: 'string',
15
16
/**
17
* Version number of the user record
18
* User for optimistic locking
19
*/
20
version: Number,
21
22
/**
23
* Creation date of the user record
24
*/
25
created_at: 'ISO8601 date',
26
27
/**
28
* Last update date of the user record
29
*/
30
updated_at: 'ISO8601 date',
31
32
/**
33
* Free-form metadata object on the user
34
*/
35
metadata: Object,
36
37
/**
38
* Two-letter ISO code of the user's country.
39
* `null` if no value is provided. This property is never set automatically by Didomi.
40
*/
41
country: 'string',
42
​
43
/**
44
* Two-letter ISO country code of the last consent event for the user.
45
* The country of a consent event might differ from the initial
46
* user's country. This property stores the last seen country from
47
* the user's consent events.
48
* Auto-filled for Didomi SDK events.
49
*/
50
last_seen_country: 'string',
51
52
/**
53
* Consent status of the user
54
*/
55
consents: {
56
/**
57
* Channels that the user made choices for
58
*/
59
channels: [
60
{
61
/**
62
* Unique channel ID
63
*/
64
id: 'string',
65
66
/**
67
* Whether the user has enabled this channel or not
68
* A null value indicates that the user has not made a specific
69
* choice for the channel
70
*/
71
enabled: boolean | null,
72
73
/**
74
* Free-form metadata object
75
*/
76
metadata: Object,
77
}
78
],
79
80
/**
81
* Purposes that the user has made choices for
82
*/
83
purposes: [
84
{
85
/**
86
* Unique purpose ID
87
*/
88
id: 'string',
89
90
/**
91
* Whether the user has given consent to this purpose or not
92
* A null value indicates that the user has not made a specific
93
* choice for the purpose but might have made choices for
94
* preferences or channels
95
*/
96
enabled: boolean | null,
97
98
/**
99
* Channels that the user made choices for
100
*/
101
channels: [
102
{
103
/**
104
* Unique channel ID
105
*/
106
id: 'string',
107
108
/**
109
* Whether the user has enabled this channel or not
110
* A null value indicates that the user has not made a specific
111
* choice for the channel
112
*/
113
enabled: boolean | null,
114
115
/**
116
* Free-form metadata object
117
*/
118
metadata: Object,
119
}
120
],
121
122
/**
123
* Extra preferences expressed for the purpose
124
*/
125
preferences: [
126
{
127
/**
128
* Unique preference ID
129
*/
130
id: 'string',
131
132
/**
133
* Whether the user has enabled this preference or not
134
* A null value indicates that the user has not made a specific
135
* choice for the preference but might have made choices for
136
* channels
137
*/
138
enabled: boolean | null,
139
140
/**
141
* Channels
142
*/
143
channels: [
144
{
145
/**
146
* Unique channel ID
147
*/
148
id: 'string',
149
150
/**
151
* Whether the user has enabled this channel or not
152
* A null value indicates that the user has not made a specific
153
* choice for the channel
154
*/
155
enabled: boolean | null,
156
157
/**
158
* Free-form metadata object
159
*/
160
metadata: Object,
161
}
162
],
163
164
165
​
166
/**
167
* Free-form metadata object on the preference
168
*/
169
metadata: Object,
170
}
171
]
172
},
173
...
174
],
175
​
176
/**
177
* Vendors that the user has made choices for
178
*/
179
vendors: {
180
/**
181
* List of vendor IDs that the user has given consent to
182
*/
183
enabled: ['string', ...],
184
185
/**
186
* List of vendor IDs that the user has denied consent to
187
*/
188
disabled: ['string', ...]
189
},
190
191
/**
192
* TCF consent string for the user
193
* (if it was available or generated at the time of consent collection)
194
*/
195
tcfcs: 'string'
196
}
197
}{
Copied!
Last modified 1mo ago