Consentric API

Using the Consentric Sign-up Form Widget - Quickstart Guide

Universal Consent & Preference Management... Made simple.

One feature of the Consentric platform is a widget that can be embedded on websites for capturing citizen consents at the point of sign up.

This page provides a simple walkthrough for embedding this widget on a static HTML page

Prerequisites

In order to use this widget you need to:

  • Have the following features enabled for your Consentric application:

    • public templates

    • unauthenticated transactions

  • Have the ID for a Consentric Template entity that defined the permissions & preferences to render

 

Finding a Template ID

When you log into the Consentric UI, assuming you have the correct privileges, in the top right there is a button that allows you to enter the admin UI:

The Content Templates page allows you to view the templates currently configured for your application.

When you first signed up to Consentric there are likely to have been default templates configured. If there aren’t any, you can create a new template for your own purposes.

Select the template you want to use in your embedded widget and select the ‘show code’ link. Within the provided code is the template’s ID. Take a copy of this for use later in this tutorial.

Embedding the Widget

The following steps will take you through embedding the widget on a web page.

1. Create a HTML Page

Create a folder to work in and using your favourite editor or IDE create a file named sign-up-form.html with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Example Sign-Up Form</title>
</head>
<body>
Example Sign-Up Form

<form id="captureForm" name="captureForm">
    <input id="a text entry field" />
    <input type="submit" value="Submit">
</form>

</body>
</html> 

Ok, so it doesn’t contain much, but if opened in a browser you should be presented with a very simple form that looks like this:

2. Embed the Widget

To embed the widget on a page you need to provide three things:

  • An element containing a unique ID for a citizen. Typically this would be generated when the page is rendered, or using logic based on data entered by a user. In this example we use a script to generate a random value on page load

  • A container for the widget to be placed into

  • A form that the widget is embedded inside. The widget will send its data to the Consentric unauthenticated store when the form’s submit event is fired.

Add the following two scripts to your page:

<script language="javascript" type="text/javascript">
    window.addEventListener('load', function () {
        var chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXTZabcdefghiklmnopqrstuvwxyz";
        var string_length = 8;
        var randomstring = '';
        for (var i=0; i<string_length; i++) {
            var rnum = Math.floor(Math.random() * chars.length);
            randomstring += chars.substring(rnum,rnum+1);
        }
        document.captureForm.referenceField.value = randomstring;
    })
</script> 
<script>
    (function () {
        var d = document, s = d.createElement('script');
        s.src = 'https://scripts.consentric.io/capture-widget.min.js';
        (d.head || d.body).appendChild(s);
    })();    window.addEventListener('load', function () {
        ConsentricCaptureWidget.load({
            templateId: '<YOUR TEMPLATE ID>',
            formSelector: '#captureForm',
            referenceSelector: '#referenceField',
            containerSelector: '#capture-widget-container'
        });
    });
</script>
 

make sure to substitute your own template ID in the code above

And then updated the form element to be as follows:

<form id="captureForm" name="captureForm">
    <input id="a text entry field" />
    <br>
    <input id="referenceField" name="referenceField" />
    <div id="capture-widget-container"></div>
    <input type="submit" value="Submit">
</form> 

Example Code

If you wish to view the completed code base for the steps above, an example copy is provided at https://github.com/MyLifeDigital/consentric-examples/tree/master/sign-up-form-widget

Downloading Captured Consent and Importing into Consentric

Periodically the transactions you capture with the Sign-up Form Widget should be reviewed and imported into Consentric. An endpoint is provided for downloading them in the appropriate format, after reviewing them you can then upload them into Consentric via the UI or the API.

1. Obtain a JWT for Accessing the API

All calls to the Consentric API must be authorised with a JSON Web Token (JWT).

When you sign up to Consentric you will be provided with client details for accessing the API. You will be given a client ID and a client secret. These values should be used to obtain a JWT from our security provider, Auth0, with which to make API calls.

For example, the JWT can be retrieved through a client credentials flow request with the following curl command:

curl --request POST \
  --url https://consentric.eu.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"<YOUR CLIENT ID>","client_secret":"<YOUR CLIENT SECRET>","audience":"https://api.consentric.io","grant_type":"client_credentials"}'
 

This would return a response of the following form containing your JWT

{
  "access_token": "<YOUR JWT>",
  "token_type": "Bearer"
}
 

Take a copy of the JWT

2. Download the Captured Consents

The https://capture.consentric.io/transaction-capture endpoint provides the facility to download the consents captured by the widget in a CSV format.

This can be done with the following curl command:

curl --request GET 'https://capture.consentric.io/transaction-capture?includeExported=false&applicationId={{YOUR CONSENTRIC APPLICATION ID}}' \
--header 'Accept: text/csv' \
--header 'Authorization: Bearer {{YOUR CONSENTRIC JWT}}' > captured-transactions.csv 
 

This will download a CSV file with content of the following form:

requestId,uniqueReference,applicationId,sourceSystem,type,privacyPolicyId,permissionStatementId,optionType,optionId,justification,state,obtainedAt,preferenceId,reference,values,validFrom
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,Di1nh,consent,DENIED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,DeLij3,consent,DENIED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,sV2fj5,consent,DENIED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,tM4zd4,consent,DENIED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,Rrkug5,consent,DENIED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,3mgii2,consent,GRANTED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,CcA145,legitimate-interest,CLAIMED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,GJwf57,legitimate-interest,OBJECTED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,FJjyD7,consent,DENIED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,XeKgC2,consent,DENIED,2020-06-26T09:46:19.295Z,,,,2020-06-26T09:46:19.295Z
5ef5c3eb79ac522395833943,Rn0aUDJy,vDCgMTSiJbD,,preference,,,,,,,,RfsKBvM1RZS,frequency,,
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,Di1nh,consent,GRANTED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,DeLij3,consent,DENIED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,sV2fj5,consent,DENIED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,tM4zd4,consent,GRANTED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,Rrkug5,consent,DENIED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,3mgii2,consent,DENIED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,CcA145,legitimate-interest,OBJECTED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,GJwf57,legitimate-interest,OBJECTED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,FJjyD7,consent,DENIED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,permission,EqxLsLSN9EH,ACYGtstnFGG,option,XeKgC2,consent,DENIED,2020-06-26T09:46:22.172Z,,,,2020-06-26T09:46:22.172Z
5ef5c3ee79ac522395833944,enVXZ3ds,vDCgMTSiJbD,,preference,,,,,,,,RfsKBvM1RZS,frequ 

Please note: Once you export records to csv the record is marked as Exported. If you need to re-export them then the curl command will need to be altered to say includeExported=true.

3. Review the captured consents

The downloaded data should be reviewed for issues, such as duplicate entries etc. The details of how to do this are not suggested here as these will be specific to the business flows implemented by each individual Consentric client. However, the unique referenced in each row can be cross-reference with your own captured data to identify records you do not wish to import into the main Consentric platform

4. Import into Consentric

Within the Consentric Admin UI, the Import Data screen provides the facility to upload your captured transactions in the provided CSV format

Simply click on ‘+ Upload a CSV’, select the CSV file you just downloaded and upload it for processing.

4 (Alternative). Import into Consentric

Alternatively, if you wish to automate the import process you can programmatically POST the CSV to the Consentric API captured-transactions-import endpoint as illustrated by the following Curl command:

curl --request POST 'https://api.consentric.io/captured-transactions-import?applicationId=<YOUR CONSENTRIC APPLICATION ID>' \
--header 'Authorization: Bearer <YOUR CONSENTRIC API JWT>' \
--form 'file=@/PATH/TO/YOUR/FILE.csv' 

The response from the API will look as follows and include a Job Id:

The Job ID can then be used to track processing progress via the same endpoint

curl --location --request GET 'https://api.consentric.io/captured-transactions-import/<JOB ID>' \
--header 'Authorization: <YOUR CONSENTRIC API JWT>' 

Which will return responses of the following form:

The status field will continue to show as IN_PROGRESS until all the records have been imported.

If all the records have successfully imported the status field will show as COMPLETE.

If there were problems with the import the status field will show as COMPLETE_WITH_FAILURES.

To review the failures amend the endpoint with the following:

curl --location --request GET 'https://api.consentric.io/captured-transactions-import/<JOB ID>/failures?applicationId=<YOUR CONSENTRIC APPLICATION ID> \
--header 'Authorization: Bearer <YOUR CONSENTRIC API JWT>' \ 

Which will return responses in the following form:

You can then review and amend the import file based on the above and retry the load.

Conclusion

If you’ve followed the steps in this quick start guide, you should now have an embedded widget capturing citizen permissions, and know how to take that captured data and import it into Consentric.