Consent Groups are a way of setting up rules for scenarios when the Consent Status for an individual data subject should be overridden due to conflicting obligations of the business, but is also necessary to retain the choices that the individual made. Consent Groups can be particularly useful in a B2B context.
Example Use Case
For example, a data subject may give their consent for a Purpose of processing, such as receiving marketing emails from your company. However, the data subject may be an employee of a partner organization, and your company has an agreement with the partner to not send marketing emails to the partner's employees.
In this instance, you can record the ACTIVE Consent Status for the Data Subject, but also place the data subject in a Consent Group named "Partner Employees". You can then set a default status for the Partner Employees Consent Group of OPTED OUT for the marketing Purpose and give this precedence over the ACTIVE consent status.
As a result, when querying the data subject, you will be able to see that as a member of the Partner Employees Consent Group, that particular data subject will be given an Effective Consent Status of OPTED OUT for the marketing Purpose, even though their Consent Status outside of that context remains Active.
This means that if the data subject stops being an employee of the partner, you can remove them from the Partner Employees Consent Group. When the data subject is removed from that Consent Group, the Effective OPTED OUT Status will also be removed. You will also still have an ACTIVE consent record for the marketing Purpose that would allow you to send marketing emails without needing to seek new consent.
Steps
- Step 1: Get and Set the Priority Rules for Calculating the Effective Status of a Data Subject
- Step 2: Create a Consent Group
- Step 3: Set up Purpose Rules for the Consent Group
- Step 4: Add a Data Subject to the Consent Group
- Step 5: Look up the Effective Status of a Data Subject
Note: Consent Groups can support a hierarchical structure of up to 4 levels deep, allowing for multiple different ways to filter and apply the business rules. However, the following steps will only focus on a single level structure.
Step 1: Get and Set the Priority Rules for Calculating the Effective Status of a Data Subject
The priority rules for a Purpose status are set at the account level. All Purpose Statuses are given a priority score, which is used to calculate the Effective Status of a Data Subject. A Purpose Status with a lower priority score will be given precedence over a Purpose Status with a higher priority score.
For example, suppose the ACTIVE status has been set with a priority of 6, and the WITHDRAWN status has been set with a priority of 3. If the priority rule for a Purpose in a Consent Group is set to WITHDRAWN and the Data Subject Consent Status is ACTIVE for the same Purpose, the data subject's Effective Status will be set to 'WITHDRAWN' since it has the lower priority score.
Note: There is a default set of priority scores for all Purpose Statuses. OneTrust reconmmends that you modify these priority scores to achieve the desired outcomes for your organization's use case and business needs. Any new Purpose Statuses will automatically be given a higher priority score so that they do not interfere with the existing rules that you have set up.
To set the priority rules, the first step will be to retrieve the existing priority scores using the GET /consent/v2/consent-groups/settings endpoint.
Example Request:
GET /api/consent/v2/consent-groups/settings
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token})
Example Response Body:
{
"statusPriorityRules": [
{
"status": "EXPIRED",
"priority": 0
},
{
"status": "HARD_OPT_OUT",
"priority": 1
},
{
"status": "OPT_OUT",
"priority": 2
},
{
"status": "WITHDRAWN",
"priority": 3
},
{
"status": "NO_CONSENT",
"priority": 4
},
{
"status": "PENDING",
"priority": 5
},
{
"status": "ACTIVE",
"priority": 6
},
{
"status": "EXTEND",
"priority": 7
},
{
"status": "ALWAYS_ACTIVE",
"priority": 8
}
]
}
You can then use the response body above as your request body template for the PUT /consent/v2/consent-groups/settings endpoint. You can use this endpoint to update the current priority values for the Purpose Statuses, as necessary. The response body received from this endpoint will display in the same format as above with the new values.
Example Request:
PUT /api/consent/v2/consent-groups/settings
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token})
Example Request Body:
{
"statusPriorityRules": [
{
"status": "EXPIRED",
"priority": 8
},
{
"status": "HARD_OPT_OUT",
"priority": 7
},
{
"status": "OPT_OUT",
"priority": 6
},
{
"status": "WITHDRAWN",
"priority": 5
},
{
"status": "NO_CONSENT",
"priority": 4
},
{
"status": "PENDING",
"priority": 3
},
{
"status": "ACTIVE",
"priority": 2
},
{
"status": "EXTEND",
"priority": 1
},
{
"status": "ALWAYS_ACTIVE",
"priority": 0
}
]
}
Step 2: Create a Consent Group
Once your priority rules have been set, you can create a Consent Group. To create a new Consent Group, you'll use the POST /consent/v2/consent-groups endpoint. In the request body, you'll provide a name and description of the Consent Group. You can also optionally assign an external name, but if you do not, one will be generated automatically.
Example Request:
PUT /api/consent/v2/consent-groups
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token})
Example Request Body:
{
"name": "OneTrust Atlanta",
"description": "Consent for the company OneTrust, specifically for the Atlanta Office",
"externalName": "onetrust_atlanta"
}
Example Response Body:
{
"name": "OneTrust Atlanta",
"description": "Consent for the company OneTrust, specifically for the Atlanta Office",
"externalName": "onetrust_atlanta",
"id": "b9c47a7e-b106-4f8f-986f-1057d3cb1cfd",
"membershipType": "EMPTY",
"purposeRules": [],
"dataSubjects": [],
"consentGroups": []
}
Step 3: Set up Purpose Rules for the Consent Group
Next, you'll set up the Purpose Rules for the Consent Group using the POST /consent/v2/consent-groups/{consentGroupGuid}/purpose-rules endpoint. Purpose Rules will dictate which Purposes of processing will be overridden with the defined Enforced Status for data subjects within the given Consent Group.
To set up the Purpose Rules for a Consent Group, you will need to know the Consent Group GUID, Purpose GUID, and the Purpose Status that you want to apply. You will then add the Purpose and set the Enforced Status for the purpose within the request body.
Note: The Enforced Status is simply the Purpose Status that you want to apply for that particular Purpose of processing. The Effective Status is calculated from the hierarchial structure for each Purpose.
Example Request:
POST /api/consent/v2/consent-groups/${consent-group-id}/purpose-rule
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token})
Example Request Body:
{
"purposeRules": [
{
"purposeId": "742a76c8-cf4e-4a67-91bb-4fb0efb88ac2",
"enforcedStatus": "EXPIRED"
},
{
"purposeId": "f824bb27-1cdb-4e7d-a761-8512bca0044a",
"enforcedStatus": "ALWAYS_ACTIVE"
}
]
}
Example Response Body:
{
"name": "OneTrust Atlanta",
"description": "Consent for the company OneTrust, specifically for the Atlanta Office",
"externalName": "onetrust_atlanta",
"id": "bf1645e9-8ac4-4167-9102-a408df3f06d5",
"membershipType": "EMPTY",
"purposeRules": [
{
"purposeId": "742a76c8-cf4e-4a67-91bb-4fb0efb88ac2",
"enforcedStatus": "EXPIRED",
"effectiveStatus": "EXPIRED"
},
{
"purposeId": "f824bb27-1cdb-4e7d-a761-8512bca0044a",
"enforcedStatus": "ALWAYS_ACTIVE",
"effectiveStatus": "ALWAYS_ACTIVE"
}
],
"dataSubjects": [],
"consentGroups": []
}
Step 4: Add a Data Subject to the Consent Group
After you have finished configuring your Consent Group, you can begin adding data subjects to the Consent Group, as needed. You can use the POST /consent/v2/consent-groups/{consentGroupGuid}/data-subjects endpoint to add one or more data subjects to the Consent Group.
Note: When adding data subjects to the Consent Group, you can use either the data subject identifier or the GUID of the data subject. Using the data subject identifier is more common as the GUID of a Data Subject is less likely to be known. Examples for both options are provided below.
Example Request:
POST //consent/v2/consent-groups/b9c47a7e-b106-4f8f-986f-1057d3cb1cfd/data-subjects
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token})
Example groupid: b9c47a7e-b106-4f8f-986f-1057d3cb1cfd
Example Request Body using the Data Subject Identifier:
{
"dataSubjects": [
{
"identifier": "[email protected]"
}
]
}
Example using the GUID of the Data Subject:
{
"id": "54b9162c-0c47-425e-ae8c-999360184521"
}
Example Response Body:
{
"name": "OneTrust Atlanta",
"description": "Consent for the company OneTrust, specifically for the Atlanta Office",
"externalName": "onetrust_atlanta",
"consentGroupId": "bf1645e9-8ac4-4167-9102-a408df3f06d5",
"membershipType": "DATA_SUBJECTS",
"purposeRules": [
{
"purposeId": "f824bb27-1cdb-4e7d-a761-8512bca0044a",
"enforcedStatus": "ALWAYS_ACTIVE",
"effectiveStatus": "ALWAYS_ACTIVE"
}
],
"dataSubjects": [
{
"id": "e78a59a8-033f-40e9-9c5e-bd3e86754f2b",
"identifier": "[email protected]",
"purposes": [
{
"id": "f824bb27-1cdb-4e7d-a761-8512bca0044a",
"version": 2,
"status": "ACTIVE",
"effectiveStatus": "ACTIVE"
}
]
}
],
"consentGroups": []
}
Step 5: Look up the Effective Status of a Data Subject
You can then use GET /consentmanager/v1/datasubjects/profiles?includeEffectiveStatus=true to look up the Effective Status of the data subject. The ?includeEffectiveStatus=true parameter will fetch the Effective Status for all Consent Groups that the data subject is a member of.
Example Request:
GET /consentmanager/v1/datasubjects/profiles?includeEffectiveStatus=true
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token})
Header:
identifier: [email protected]
Example Response Body:
{
"content": [
{
"Id": "54b9162c-0c47-425e-ae8c-999360184521",
"Language": "en-US",
"Identifier": "[email protected]",
"LastUpdatedDate": "2020-02-15T11:42:20.507",
"CreatedDate": "2020-02-15T11:42:20.507",
"DataElements": [],
"Purposes": [
{
"Id": "742a76c8-cf4e-4a67-91bb-4fb0efb88ac2",
"LastReceiptId": null,
"Name": "Purpose that is within the purpose rules of the consent group",
"Version": 1,
"Status": "ACTIVE",
"FirstTransactionDate": "2020-02-15T11:42:19.32",
"LastTransactionDate": "2020-02-15T11:42:19.32",
"WithdrawalDate": null,
"ConsentDate": "2020-02-15T11:42:20.473",
"ExpiryDate": null,
"TotalTransactionCount": 1,
"Topics": [],
"CustomPreferences": [],
"LastTransactionCollectionPointId": "61f5aeea-0b2a-4727-8521-1fb661349c45",
"LastTransactionCollectionPointVersion": 1,
"PurposeNote": null,
"GroupEffectiveStatus": [
{
"GroupId": "bf1645e9-8ac4-4167-9102-a408df3f06d5",
"EffectiveStatus": "EXPIRED" // the effective status is EXPIRED because the consent group's purpose rule effective status (EXPIRED) precedes the profile's actual status (ACTIVE)
}
]
},
...[other purposes]
]
}