Consent Database – Introduction and methods

Maintaining comprehensive records of consent are a vital part of privacy compliance in general but are specifically required under the GDPR. These records should include a way of identifying the user, proof of consent, record of the consenting action and the legal documents available to the user at the time of consent, among other things. You can read about the full requirements here.

The Consent Database provides you with an API to:

• Add, revoke, manage user consent
• Store multiple preferences for each user (e.g. if you have multiple newsletters or opt-ins)
• Store whether a user was verified with double opt-in
• Store additional information about the user, allowing you to identify him/her in the future
• For each consent, track the legal or privacy notice the user has accepted
• For each consent, track the form/wording the user was prompted with
• Flexibly upload any form of proof of consent or legal notice, including a PDF if consent was collected on paper
• For each user, get the latest preferences and which consent action is the proof of consent
• For each user, get the history of consents

Different ways of accessing the API

You can access the API via HTTP, or through our JavaScript library. The JavaScript library also comes with a few extra features, such as:

• Extracting the consent data automatically from a form
• Asynchronous saving via localstorage

The methods are the same for all the interfaces and are explained below. Each interface has its own specific integration instructions and specific features, which are explained in the respective guides:

• HTTP API Documentation
• JavaScript library Documentation

Key differences

• The HTTP API must be authenticated with the private key, the JavaScript library with the public key
• the JavaScript API only supports write actions, not read ones

Consent Dashboard

The aesthetic and user-friendly visual Dashboard allows you to easily sort, analyze and review your consent records.

You can find your Consent Database Dashboard by simply visiting your main account dashboard > [Your website/app], then Consent Database > Consent Database Dashboard.

Once you’ve collected your consents, sorting and analyzing your user consent data are made practically pain-free as records are categorized by “Consents”, “Subjects” and “Legal Notices”:

Furthermore, the color scheme is designed to provide visual cues regarding the status of consent preferences for each subject listed:

• GREEN Active consent (true).
• RED Inactive consent (false).
• GREY Indicates an undetermined or unspecified consent status when a checkbox lacks a boolean value.

You can click on the icons on the right side of the table for easy access to individual user, consent and legal notices details:

Or use the powerful search function to find subjects, consents or legal notices:

You even can apply detailed filters specific to the table you’re searching.

See the dashboard in action here:

Technical Overview

The Consent Database has the purpose of allowing you to save consent actions performed by your users (here called subjects) and to store all the information necessary to hold a proof. These consent actions result in a series of values saved about your subjects/users, which you can later recall via a dedicated endpoint. These values include the user’s preferences (newsletter, profiling, etc) that each consent section has modified.

Naming conventions

• Subject: the person the personal data is referred to, which generally coincides with the user
• Consent: the action of providing consent. Each consent action contains all the information necessary to uniquely identify that specific consent, the subject who performed it, the preferences expressed with that consent, the legal notices the user has accepted, the proof (e.g. the form the user was presented with)
• Preferences: the various opt-ins the user has agreed to, such as newsletter, profiling, etc.

Example of implementation flow

The implementation flow will generally look like this:

1. Identify all the preferences you collect from subjects (general, newsletter emailing, behavioral emailing, profiling etc)
2. Determine what unique identifier to send to the Consent Database to later access consents and preferences for each subject. This field is not mandatory, and if you don’t provide one, we’ll assign an auto-generated subject ID
3. Identify all points where the subject can change its preferences, such as:
   • At signup
   • When subscribing to the newsletter
   • When verifying the user via double opt-in
   • In the preferences page the user has in your dashboard
4. Send a consent call for each

The Consent Database is flexible enough to be used in the most disparate scenarios, including offline scenarios, such as storing any consents that have been collected on paper.

Methods and properties

Consent

This method is used to send consent events. You can write and read, but you cannot modify existing consent events. Keep consents as a log history of the consents that the subject has provided, whether they’ve affected or not its preferences.

Properties

`timestamp`

Type: string (ISO 8601 timestamp)
Default value: auto-filled if not provided
Description: The timestamp at which the consent occurred

subject ([id], [email], [first_name], [last_name], [full_name], [verified])

Type: hash
Description: Wrapper for the subject set of properties, which can be saved both via the Subject method and from within the Consent method. Check the Subject method for the properties supported within this set.
Note: subject.id will be auto-filled if not provided.

legal_notices ([identifier], [version])

Type: array (accepts multiple objects)
Description: array of the legal notices to attach to the consent event, identified by their identifier and version. If version is not provided, the latest available will be used. Accepts the following fields:

• identifier, string, used to pass an identifier of your legal documents. Accepts semantic names or custom values. Pre-defined semantic names are:
  • privacy_policy
  • cookie_policy
  • terms
• version, string, used to specify the version of legal documents that your user has accepted. Default is the latest available.

proofs ([form], [content])

Type: array (accepts multiple objects)
Description: array of the proofs to attach to the consent event. It’s normally used to attach what the subject was prompted with (e.g. the form) and what the subject has filled (e.g. the content of the form).
Accepts the following fields:

• form, string, used to include the form
• content, string, used to include the content of the form

In some cases, like if you’re uploading a paper form, uploading only one of the two (such as content) which contains both the form and the content, will be sufficient.

preferences ({ [preference_name]: [preference_value], ... })

Type: hash
Description: set of key-value pairs with preferences that you’re saving with the consent action. These preferences will also be updated for the subject and will be retrievable with the Subject method. It’s advisable to define a preferences naming and stick to it for all your calls. For instance, you could pass:

• general: true|false
• newsletter: true|false
• profiling: true|false
• etc.

Subject

This method allows you to save subject information, and to retrieve them.

Properties you can write

id

Type: string
Default value: auto-filled if not provided
Description: To uniquely identify your subjects. Will be auto-generated if not provided. It’s advisable to either send an identifier that you already have in your database, or store the identifier that we generate and then provide in the callback, so that you can later retrieve a subject and update its preferences or send further consent events.

email
first_name
last_name
full_name

Type: string
Description: For your convenience, so that you can more easily identify a subject.

verified

Type: bool
Description: Reserved field used to signal whether a subject is verified, for instance via the double opt-in method

Read only properties

preferences ()

Type: hash
Description: contains the most updated preferences the user has provided via the consent events. Including the latest consent ID for each preference.

Legal_notices

This method allows you to store the legal notices that you can then reference under consent → legal_notices.

E.g. you have the following legal notices:

• Privacy Policy
• Cookie Policy
• Terms and Conditions

At the first setup and whenever you update them, you can use this method to update the version. If you use iubenda for your legal documents, we’ll automatically update the contents of this method for you whenever your legal documents are changed.
You can read about how to enable this feature here.

Each time a new or existing legal_notice is filled, we’ll bump the version field by 1, starting from 1.

Properties

legal_notices 
    (
        { 
            identifier: [ privacy_policy|cookie_policy|terms|[custom] ], 
            content: [the actual legal text]
            timestamp: [date] // auto-generated, but can be overridden
            version: [1+] // progressive number, auto-generated, cannot be overridden
        }
    )

Accepts the following fields:

• identifier, string, used to pass an identifier of your legal documents. Accepts semantic names or custom values. Pre-defined semantic names are:
  • privacy_policy
  • cookie_policy
  • terms
• content, string or hash, the actual legal text that you’ll prompt the user with. You can store multilanguage content by passing a hash having the following structure { [language_code]: [content], ... }
• timestamp, date, auto-generated, but can be overridden, should be customized with the time of update of the legal notice. By default it’s filled with the time the call is performed at
• version, number, auto-generated, cannot be overridden

See also

• How to Sync Your iubenda Legal Documents with the Consent Database
• Consent Database – JS Documentation
• Consent Database – HTTP API Documentation
• How to use the Consent Database with Contact Form 7