Events
A consent event is a partial update to the consent status of a user. When a user makes consent choices through a Didomi SDK (a consent notice, for instance) or through your own custom UI, you should create a new consent event on the Didomi platform. The user consent status will be automatically updated and the history of consent events will be kept, associated with the user.
The /consents/events endpoint of the API exposes the events 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 event

When a user gives consent to a set of purposes or vendors, create a consent event to register the user choices by calling the POST /consents/events endpoint.
A consent event consists of a set of partial choices from a user that will be merged into the user consent status. You can also send additional user information like a new ID or custom metadata. When pushing consent events, you do not need to know the prior consent status of the user and the consent information you are pushing will be automatically merged into the user consent status of the Users endpoints.
Example
A user giving consent to the purpose "purpose_id":
1
POST /consents/events?organization_id={organization_id}
2
3
BODY
4
{
5
"user": {
6
"organization_user_id": "[email protected]",
7
"metadata": {
8
"custom_key": "value"
9
}
10
},
11
12
"consents": {
13
"purposes": [
14
{
15
"id": "purpose_id",
16
"enabled": true
17
}
18
]
19
}
20
}
Copied!
You can specify either the user.organization_user_id field with your own organization user ID or a user.id field with the Didomi user ID. If you do not specify any user ID, a random ID will be automatically created for the user.

Proofs

If you are collecting physical proofs of consents from your users (signatures, forms, etc.), you can attach them to the created events. Add your files as base64-encoded data URIs in the proofs property:
1
POST /consents/events?organization_id={organization_id}
2
3
BODY
4
{
5
"user": {
6
"organization_user_id": "[email protected]",
7
"metadata": {
8
"custom_key": "value"
9
}
10
},
11
12
"consents": {
13
"purposes": [
14
{
15
"id": "purpose_id",
16
"enabled": true
17
}
18
]
19
},
20
21
"proofs": [
22
{
23
"filename": "proof.png",
24
"file: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
25
}
26
]
27
}
Copied!
Files must be smaller than 10mb and their type must be one of the following formats: PDF, PNG, JPG, GIF, DOCX, DOC, MSG. You can attach a maximum of 5 proofs per event.

Pending events and approval process

By default, created events are confirmed: their status property has the value confirmed. This indicates that the event is valid and was applied to the user consent status.
Didomi supports various approval methods (email confirmation, email approval, etc.) where an event needs to be approved in a separate process before being applied to the user consent status. Such events are considered "pending" as they are created and stored in the API but not applied to the user consent status until the event is approved. Their status property is set to pending_approval.
When an event is updated to become confirmed, the Didomi API will automatically update the user consent status to apply the updated event. Events will be re-applied according to their update or creation date so that the most recent confirmed events will be applied last.

Create pending events

Events are automatically created as pending if you use a validation method or a consent token with a validation method associated.
If you are not using a validation method and want to create pending events yourself, you can do so by specifying pending_approval in the status property:
1
POST https://api.didomi.io/v1/consents/events?organization_id={organization_id}
2
{
3
"status": "pending_approval",
4
"user": {
5
"organization_user_id": "{organization_user_id}"
6
}
7
}
Copied!
A pending event must include an organization_user_id. It also requires an event ID in the id property that will be automatically generated if you do not provide it.

Approve pending events

The Didomi API supports three methods for approving pending events.

Approve pending events via validation methods

When a validation method is used, the approval process is entirely managed by the Didomi API through emails or similar methods. The Didomi API will also takes care of updating the event status when the event is approved through the validation method.

Approve pending events via API requests

If you are not using validation methods, you can manage the approval process yourself and approve pending events through API requests.
To approve pending events, update the event and set the status property to confirmed with a PATCH request:
1
PATCH https://api.didomi.io/v1/consents/events/{event_id}?organization_id={organization_id}&organization_user_id={organization_user_id}
2
{
3
"status": "confirmed"
4
}
Copied!

Approve pending events via an approval URL

When an event is in status pending_approval, an approval URL is added in the validation.approve_url property. Example of an event with an approval URL provided:
1
{
2
"user": {
3
"organization_user_id": "[email protected]",
4
"metadata": {
5
"custom_key": "value"
6
}
7
},
8
9
"consents": {
10
"purposes": [
11
{
12
"id": "purpose_id",
13
"enabled": true
14
}
15
]
16
},
17
18
"status": "pending_approval",
19
20
"validation": {
21
"approve_url": "https://api.privacy-center.org/consents/execute/..."
22
}
23
}
Copied!
This URL can be used to easily approve the event without requiring API authentication and API calls. It is safe to embed in emails, webpages, etc. as links that users can click on to approve the event.

Delegates

Delegates are third-parties that modify the consents for an end user and that you want to keep track of. They can be an internal team or user that have been given access to the Didomi API. The third-party is a "delegate" who is doing modifications on behalf of the end user. Delegate information is optional and can be added to the event to keep track of the modification and its source for audit purposes.
Provide the delegate property when creating a consent event to indicate that the event was created by a delegate. You can specify the ID and name of the delegate, and use a generic metadata field to keep track of extra information on the delegate.
Example - Tracking an internal employee ID and their department when an event is created
1
POST /consents/events?organization_id={organization_id}
2
3
BODY
4
{
5
"user": {
6
"organization_user_id": "[email protected]",
7
"metadata": {
8
"custom_key": "value"
9
}
10
},
11
12
"consents": {
13
"purposes": [
14
{
15
"id": "purpose_id",
16
"enabled": true
17
}
18
]
19
},
20
21
"delegate": {
22
"id": "<Internal ID to identify the delegate>",
23
"name": "<Name of the delegate>",
24
"metadata": {
25
// Custom metadata of the delegate
26
"department_id": "...",
27
"country": "..."
28
}
29
}
30
}
Copied!
Delegates can also be used with consent tokens.

Query consent events

You can query consent events for a user by calling the GET /consents/events endpoint.
You must specify either the organization user ID (organization_user_id query-string parameter) or the Didomi user ID (user_id query-string parameter) of the user that you are querying events for.
Example
1
GET /consents/events?organization_id={organization_id}&organization_user_id={organization_user_id}
2
3
RESPONSE:
4
{
5
"data": [
6
{
7
"id": "00b89328-e3d5-4068-b346-8f4fcb4618df",
8
9
"user": {
10
"id": "a3722cd3-f2e4-4451-a564-83f5e8921449",
11
"metadata": {
12
...custom user metadata
13
}
14
},
15
16
"consents": {
17
"purposes": [
18
{
19
"id": "purpose_id",
20
"enabled": true
21
}
22
]
23
}
24
}
25
]
26
}
Copied!

Pending events

By default, the GET /consents/events endpoint only returns confirmed events. To get pending events, you must specify a status filter in the query-string parameter.
For instance, to get all confirmed and pending events, you would do:
1
GET /consents/events?organization_id={organization_id}&organization_user_id={organization_user_id}&status[$in]=confirmed&status[$in]=pending_approval
2
3
RESPONSE:
4
{
5
"data": [
6
{
7
"id": "00b89328-e3d5-4068-b346-8f4fcb4618df",
8
9
"user": {
10
"id": "a3722cd3-f2e4-4451-a564-83f5e8921449",
11
"metadata": {
12
...custom user metadata
13
}
14
},
15
16
"consents": {
17
"purposes": [
18
{
19
"id": "purpose_id",
20
"enabled": true
21
}
22
]
23
}
24
}
25
]
26
}
Copied!

Specific event

You can also query for a specific event by ID by calling GET /consents/events/:id. See the API documentation for more details.

Delete consent events

You can delete consents events by calling the DELETE /consents/events endpoint.
When deleting consent events, the user consent status will be automatically re-computed by re-applying the remaining (non-deleted) consent events.
You must specify either the organization user ID (organization_user_id query-string parameter) or the Didomi user ID (user_id query-string parameter) of the user that you are querying events for.
You must also specify a list of filters as key-value pairs in the query-string parameters to select consent events that should be removed. The key should be a property name from the Event Schema with nested properties path specified with a .. For instance, a custom event metadata field can be specified as metadata.custom_key.
Example
1
DELETE /consents/events?organization_id={organization_id}&organization_user_id={organization_user_id}&metadata.booking_id={booking ID}
Copied!
You can also delete a specific event by ID by calling DELETE /consents/events/:id. See the API documentation for more details.

Event Schema

The full schema of Events is as follows:
1
{
2
/**
3
* Unique event ID
4
* Automatically generated by the API if not provided on event creation
5
*/
6
id: 'string',
7
8
/**
9
* Creation date of the event
10
* Automatically generated by the API if not provided on event creation
11
*/
12
created_at: 'ISO8601 date',
13
14
/**
15
* Free-form metadata object
16
*/
17
metadata: Object,
18
19
/**
20
* User information
21
*/
22
user: {
23
/**
24
* Didomi user ID
25
*/
26
id: 'string',
27
28
/**
29
* Organization user ID
30
*/
31
organization_user_id: 'string',
32
33
/**
34
* Free-form metadata object
35
*/
36
metadata: Object,
37
38
/**
39
* Two-letter ISO code of the user's country.
40
* `null` if no value is provided. This property is never set automatically by Didomi.
41
*/
42
country: 'string',
43
44
/**
45
* Two-letter ISO country code of the consent event.
46
* The country of a consent event might differ from the initial
47
* user's country. This property stores the last seen country from
48
* the user's consent events.
49
* Auto-filled for Didomi SDK events.
50
*/
51
last_seen_country: 'string'
52
},
53
54
/**
55
* IDs of proofs associated with this event
56
*/
57
proofs_id: [ ... ],
58
59
/**
60
* Delegate that created the event
61
* `null` if there is no delegate
62
*/
63
delegate: {
64
/**
65
* Unique ID of the delegate
66
*/
67
id: 'string',
68
69
/**
70
* Name of the delegate
71
*/
72
name: 'string',
73
74
/**
75
* Free-form metadata object
76
*/
77
metadata: Object,
78
},
79
80
/**
81
* Validation information (if the event was validated)
82
* `null` if there is no validation
83
*/
84
validation: {
85
/**
86
* Validation type used for this event
87
*/
88
type: 'email|signature|file'
89
},
90
91
/**
92
* Status of the event
93
*
94
* "confirmed" indicates that the event has been validated or was not subject to validation
95
* "pending_approval" indicates that the event is pending validation
96
*/
97
status: 'confirmed|pending_approval',
98
99
/**
100
* Domain of the preference center
101
*
102
* This is used to know which preference center is this consent linked to.
103
* For example to send a authenticated link to the preference center on user creation
104
*/
105
domain: 'string'
106
107
/**
108
* Consent status of the user
109
*/
110
consents: {
111
/**
112
* Channels that the user made choices for
113
*/
114
channels: [
115
{
116
/**
117
* Unique channel ID
118
*/
119
id: 'string',
120
121
/**
122
* Whether the user has enabled this channel or not
123
* A null value indicates that the user has not made a specific
124
* choice for the channel
125
*/
126
enabled: boolean | null,
127
128
/**
129
* Free-form metadata object
130
*/
131
metadata: Object,
132
}
133
],
134
135
/**
136
* Purposes that the user has made choices for
137
*/
138
purposes: [
139
{
140
/**
141
* Unique purpose ID
142
*/
143
id: 'string',
144
145
/**
146
* Whether the user has given consent to this purpose or not
147
* A null value indicates that the user has not made a specific
148
* choice for the purpose but might have made choices for
149
* preferences or channels
150
*/
151
enabled: boolean | null,
152
153
/**
154
* Channels that the user has made choices for
155
*/
156
channels: [
157
{
158
/**
159
* Unique channel ID
160
*/
161
id: 'string',
162
163
/**
164
* Whether the user has enabled this channel or not
165
* A null value indicates that the user has not made a specific
166
* choice for the channel
167
*/
168
enabled: boolean | null,
169
170
/**
171
* Free-form metadata object
172
*/
173
metadata: Object,
174
}
175
],
176
177
/**
178
* Extra preferences expressed for the purpose
179
*/
180
preferences: [
181
{
182
/**
183
* Unique preference ID
184
*/
185
id: 'string',
186
187
/**
188
* Whether the user has enabled this preference or not
189
* A null value indicates that the user has not made a specific
190
* choice for the preference but might have made choices for
191
* channels
192
*/
193
enabled: boolean | null,
194
195
/**
196
* Channels that the user has made choices for
197
*/
198
channels: [
199
{
200
/**
201
* Unique channel ID
202
*/
203
id: 'string',
204
205
/**
206
* Whether the user has enabled this channel or not
207
* A null value indicates that the user has not made a specific
208
* choice for the channel
209
*/
210
enabled: boolean | null,
211
212
/**
213
* Free-form metadata object
214
*/
215
metadata: Object,
216
}
217
],
218
219
220
221
/**
222
* Free-form metadata object on the preference
223
*/
224
metadata: Object,
225
}
226
]
227
},
228
...
229
],
230
231
/**
232
* Vendors that the user has made choices for
233
*/
234
vendors: {
235
/**
236
* List of vendor IDs that the user has given consent to
237
*/
238
enabled: ['string', ...],
239
240
/**
241
* List of vendor IDs that the user has denied consent to
242
*/
243
disabled: ['string', ...]
244
},
245
246
/**
247
* TCF consent string for the user
248
* (if it was available or generated at the time of consent collection)
249
*/
250
tcfcs: 'string'
251
}
252
}
Copied!
Last modified 4mo ago