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

POST /consents/events?organization_id={organization_id}
BODY
{
"user": {
"organization_user_id": "user@domain.com",
"metadata": {
"custom_key": "value"
}
},
"consents": {
"purposes": [
{
"id": "purpose_id",
"enabled": true
}
]
}
}

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.

See the API documentation for more details on this endpoint.

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

GET /consents/events?organization_id={organization_id}&organization_user_id={organization_user_id}
RESPONSE:
{
"data": [
{
"id": "00b89328-e3d5-4068-b346-8f4fcb4618df",
"user": {
"id": "a3722cd3-f2e4-4451-a564-83f5e8921449",
"metadata": {
...custom user metadata
}
},
"consents": {
"purposes": [
{
"id": "purpose_id",
"enabled": true
}
]
}
}
]
}

See the API documentation for more details on this endpoint.

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

DELETE /consents/events?organization_id={organization_id}&organization_user_id={organization_user_id}&metadata.booking_id={booking ID}

See the API documentation for more details on this endpoint.

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:

{
/**
* Unique event ID
*/
id: 'string',
/**
* Creation date of the event
*/
created_at: 'ISO8601 date',
/**
* Free-form metadata object
*/
metadata: Object,
/**
* User information
*/
user: {
/**
* Didomi user ID
*/
id: 'string',
/**
* Organization user ID
*/
organization_user_id: 'string',
/**
* Free-form metadata object
*/
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', ...]
}
}
}