Consentric API
Using the Consentric API - Java Step By Step Example
Universal Consent & Preference Management... Made simple.
QuickStart Guides
Additional Resources
Developer Plans
Prerequisites
When you signed up to Consentric you will have had an application created for you with some basic configuration and a client will have been configured for you to access the API. In order to work through this guide you will need the following details:
Your API client ID
Your API client secret
Your Consentric application ID
In ID of a privacy policy configured within your Consentric application
An ID of an Option configured within your Consentric application
An ID of a Permission Statement configured within your Consentric application
You will also need the following software installed:
Obtaining Consentric Entity IDs
If you don’t know the prerequisite Consentric entity IDs, you can retrieve these from the Consentric admin UI.
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:

Once logged into the admin UI you can obtain an ID for one of your configured options from within the ‘Configuration’ screen

Within the ‘Privacy Policies’ screen you can obtain the ID of the privacy policy you intend to use:

Within the ‘Permission Statements’ screen you can retrieve the ID of the permission statement you intend to use:

Building your Java client
1. Initialise a Gradle Project
Make a directory for your client and execute the following command line within it
gradle init
-
You will be asked for various settings, use the following:
-
Type of project – application
-
Language to use – Java
-
Build script DSL – Groovy
-
Test framework – JUnit 4
-
Other settings – use defaults
This will build you a skeleton application that can be executed with the command
-
./gradlew run
2. Add Unirest Dependency
This example uses the Unirest library making HTTP requests.
In your project’s build.gradle file remove the guava dependency that Gradle has added (we do need this) and add an implementation dependency for com.konghq:unirest-java so that your dependencies will look like this:
dependencies {
implementation 'com.konghq:unirest-java:3.7.02'
// Use JUnit test framework
testImplementation 'junit:junit:4.12'
}
3. Declare your input parameters
In the generated project you will find a class named App within the src/main/java/ folder.
Add the following constant declarations to the top of this class, substituting your own values for the client ID and secret
public class App {
private static final String CLIENT_ID = "<YOUR CLIENT ID>";
private static final String CLIENT_SECRET = "<YOUR CLIENT SECRET>";
private static final String API_AUDIENCE = "https://api.consentric.io";
4. Retrieve a JWT
Set the imports at the top of the App class to be the following:
import kong.unirest.HttpResponse;
import kong.unirest.JsonNode;
import kong.unirest.Unirest;
Now replace your main method with the following code:
public static void main(String[] args) {
HttpResponse<JsonNode> httpResponse = Unirest.post("https://consentric.eu.auth0.com/oauth/token")
.header("content-type", "application/json")
.body("{\"client_id\":\"" + CLIENT_ID + "\",\"client_secret\":\"" + CLIENT_SECRET + "\",\"audience\":\"" + API_AUDIENCE + "\",\"grant_type\":\"client_credentials\"}")
.asJson();
if (httpResponse.getStatus() != 200) {
System.out.printf("Error obtaining JWT: %s\n", httpResponse.getBody());
System.exit(1);
}
String access_token = (String) httpResponse.getBody().getObject().get("access_token");
System.out.printf("Retrieved JWT\n");
}
If you execute ./gradlew run your application will now execute and confirm that it has obtained a JWT
5. Create a Citizen
Add the following declarations to the top of your App class, substituting your own IDs:
private static final String BASE_URL = "https://api.consentric.io";
private static final String APPLICATION_ID = "<YOUR APPLICATION ID>";
private static final String PRIVACY_POLICY_ID = "<YOUR PRIVACY POLICY ID>";
private static final String OPTION_ID = "<YOUR OPTION ID>";
private static final String PERMISSION_STATEMENT_ID = "<YOUR PERMISSION STATEMENT ID>";
Add the following code to the end of your main method:
String citizenReference = UUID.randomUUID().toString(); // Citizen references should be unique strings
String citizen = "{\n" +
" \"applicationId\": \"" + APPLICATION_ID + "\",\n" +
" \"externalRef\": \"" + citizenReference + "\",\n" +
" \"givenName\": \"Test\",\n" +
" \"familyName\": \"Citizen2\",\n" +
" \"address\": {\n" +
" \"streetAddress\": \"23 Acacia Avenue\",\n" +
" \"addressLocality\": \"Trust Town\",\n" +
" \"addressRegion\": \"Gloucestershire\",\n" +
" \"addressCountry\": \"UK\",\n" +
" \"postalCode\": \"TT1 1AS\"\n" +
" }\n" +
"}";
HttpResponse<JsonNode> createCitizenResponse = Unirest.post(BASE_URL + "/v1/citizens")
.header("content-type", "application/json")
.header("Authorization", "Bearer " + access_token)
.body(citizen)
.asJson();
System.out.printf("Citizen created: %s\n\n", createCitizenResponse.getBody().toPrettyString());
Your application will now create a new citizen in Consentric on each execution.
6. Submit a Transaction for the Citizen
Citizen contents and permissions are updated in Consentric by submitting transactions.
Each transaction can contain multiple changes to be applied and each change should specify the specific ‘Option’ to be changed and the new values to be applied.
A transaction should also state the IDs of the Privacy Policy and Permission Statement that that applied at the time the Citizen’s consents were obtained.
Add the following code to the end of your main method:
String citizenTransactions = "{\n" +
" \"applicationId\": \"" + APPLICATION_ID + "\",\n" +
" \"externalRef\": \"" + citizenReference + "\",\n" +
" \"changes\": [\n" +
" {\n" +
" \"optionType\": \"option\",\n" +
" \"optionId\": \"" + OPTION_ID + "\",\n" +
" \"justification\": \"consent\",\n" +
" \"state\": \"GRANTED\"\n" +
" }\n" +
" ],\n" +
" \"privacyPolicyId\": \"" + PRIVACY_POLICY_ID + "\",\n" +
" \"permissionStatementId\": \"" + PERMISSION_STATEMENT_ID + "\"\n" +
"}";
HttpResponse<JsonNode> transactionPostResponse = Unirest.post(BASE_URL + "/v1/permissions/transactions")
.header("content-type", "application/json")
.header("Authorization", "Bearer " + access_token)
.body(citizenTransactions)
.asJson();
if (transactionPostResponse.getStatus() != 200) {
System.out.printf("Error creating transaction: %s\n", transactionPostResponse.getBody());
System.exit(1);
}
System.out.printf("transaction POST response: %s\n\n", transactionPostResponse.getBody().toPrettyString());
try {
Thread.sleep(1000); // Allow consentric to process the transaction
} catch (InterruptedException e) {
e.printStackTrace();
}
7. Retrieve a citizen's permissions
In this final step we add code to retrieve the created citizens permissions.
Add the following code to the end of your main method:
HttpResponse<JsonNode> permissionsResponse = Unirest.get(BASE_URL + "/v1/permissions")
.header("content-type", "application/json")
.header("Authorization", "Bearer " + access_token)
.queryString("applicationId", APPLICATION_ID)
.queryString("externalRef", citizenReference)
.asJson();
if (permissionsResponse.getStatus() != 200) {
System.out.printf("Error getting citizen permissions: %s\n", permissionsResponse.getBody());
System.exit(1);
}
System.out.printf("Retrieved permissions: %s\n\n", permissionsResponse.getBody().toPrettyString());
On execution, your application will now create a citizen, updated their recorded permissions, and retrieve them again.
Summary
If you have followed the steps in this guide correctly you will have a basic Java client for the Consentric API
A completed example is available to be viewed and downloaded from GitHub
This is by no means a fully fledged production grade client, but should give any developer a good starting point for developing their own Consentric clients.