Get List of Data Subjects
Use this API to retrieve a list of all data subjects. The response will include details for each data subject such as data elements, purposes, associated topics, and purpose preferences. The response will also include relevant information about the latest Collection Point interactions and receipt IDs, along with the current status of consent for the purposes and preferences they have interacted with.
🗒 Things to Know
- It is critical that all queries include properties=ignoreCount. Not including ignoreCount will significantly decrease performance. If you need the count, we advise to only include it in the initial query, and not for subsequent page calls.
- The values passed in the properties query parameter can change the response of this API. A fast response on large data sets can be obtained passing any of the following values: linkTokens, ignoreCount, ignoreTopics, ignoreCustomPreferences.
- This API is not designed to be used in synchronous workflows. As an alternative, the Gets preferences for a Data Subject API can be called.
- It is strongly recommended to pass the requestContinuation parameter returned in the response of this API in the next API request to paginate. Including it is crucial for better performance when dealing with multiple pages of data subject records. For more information, see Understanding & Implementing Pagination.
- When specifying a data subject identifier, only the primary identifier is supported. Additional identifiers cannot be used for search or filtering.
🚧
Please note that the FTC Do Not Call List is updated once daily and not updated in real time. As such, there may be a possibility that a consumer's preferences may have changed and they may have opted out of receiving communication before the Do Not Call list gets refreshed. OneTrust is merely conveying information received from the FTC and is not responsible for compiling the lists.
Query parameters
Restrict information to changes in consent information since a given date: formats accepted yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss. Note that the since and updatedSince parameters cannot be used in conjunction.
Filter Data Subjects records that were last updated before the specified date: formats accepted yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss. Note that the since and updatedTo parameters cannot be used in conjunction.
Filter Data Subject records that were last updated after the specified date: formats accepted yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss. Note that the since and updatedSince parameters cannot be used in conjunction.
Data subject identifier to filter results.
Restrict information to only DataSubjects related to a purpose.
Restrict information to only DataSubjects related to a collection point id.
Restrict information to only DataSubjects related to a collection point name.
Specify optional properties, any of: [linkTokens] return linkTokens, [ignoreCount] will not return a full record count, [ignoreTopics] will exclude Topics from Purposes, [ignoreCustomPreferences] will exclude Custom Preferences from Purposes. This is the preferred option for a fast response on large datasets, [includeAllPreferences] will include for all Topics and CustomPreferenceOptions attached to Purposes a boolean value specifying whether the Topic/CustomPreferenceOption has been consented to or not, [includeNotices] will include the privacy notices the data subject has consented to in each profile, eg: properties=linkTokens,ignoreCustomPreferences,includeAllPreferences
Include effective status of Data Subject Profiles (true/false).
Unique identifier identifying a Linked Identity Group.
Include consent attachments of DataSubject (true/false).
Include DNC records (true/false).
Include data subjects with no organization (true/false).
Include Geolocation parameters of the DataSubject (true/false).
Results page you want to retrieve (0..N).
Number of records per page.
Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.
Headers
Restrict information to one DataSubject.
Filter Data Subject records with Data Element name. Note that it must be used in conjunction with dataElementValue.
Filter Data Subject records with Data Element value. Note that it must be used in conjunction with dataElementName.
The token used to paginate a response if the number of records is more than a page.
Response
OK - List of data subjects retrieved successfully.
Example response
{
"content": [
{
"Id": "1b1f53d3-dc40-4288-abf1-74a4a4c33510",
"Language": "en-us",
"Identifier": "example@otprivacy.com",
"LinkToken": "jNJW2e8vm8eWb6DlWyGbZ/7PsfC+AHFN8JqvZHPGzJQ=",
"LastUpdatedDate": "2020-01-12T16:11:25.479Z",
"CreatedDate": "2020-01-12T16:11:25.479Z",
"DataElements": [
{
"Name": "Work Email",
"Linked": true
}
],
"Purposes": [
{
"Id": "f2229953-b4b5-4042-8cb9-b78038cc4c46",
"LastReceiptId": "f2229953-b4b5-4042-8cb9-b78038cc4c46",
"Name": "Marketing Communications",
"Version": 2,
"Status": "ACTIVE",
"FirstTransactionDate": "2020-01-05T11:34:30.974Z",
"LastTransactionDate": "2020-01-12T16:11:25.479Z",
"WithdrawalDate": "2020-01-12T16:11:25.479Z",
"ConsentDate": "2020-01-07T13:18:23.123Z",
"ExpiryDate": "2020-01-07T13:18:23.123Z",
"TotalTransactionCount": 3,
"Topics": [
{
"Id": "497c4383-2c61-4906-aed0-660e3fd03ef0",
"Name": "Car Marketing",
"IsConsented": true
}
],
"CustomPreferences": [
{
"Id": "c4a57a38-3774-45ad-9fa4-dbc545542232",
"Name": "Email Frequency",
"Options": [
{
"Id": "ca0fc41b-b28a-4335-804c-44d1f0f782ed",
"Name": "Weekly",
"IsConsented": true
}
]
}
],
"LastUpdatedDate": "2020-01-05T11:34:30.974Z",
"LastInteractionDate": "2020-01-05T11:34:30.974Z",
"Geolocation": {
"DataSubjectId": "633ba071-61b0-485f-81a0-a2245777b432",
"ReceiptGuid": "633ba071-61b0-485f-81a0-a2245777b432",
"Country": "US",
"State": "GA",
"StateName": "Georgia",
"CreatedDate": "2020-01-12T16:11:25.479Z"
}
}
],
"Notices": [
{
"Id": "05e30742-7e6c-4916-a5a1-7742a14ee984",
"Name": "Marketing Notice",
"Url": "https://www.onetrust.com/privacy-notice",
"Guid": "1439b150-ef4c-444c-a20e-44622c8ccaf3",
"Type": "EMBEDDED"
}
],
"attachments": [
{
"fileName": "consent_agreement.pdf",
"attachmentId": "a9adf402-adcd-45be-b981-a56a5c0739ec"
}
],
"LatestGeolocation": {
"DataSubjectId": "633ba071-61b0-485f-81a0-a2245777b432",
"ReceiptGuid": "633ba071-61b0-485f-81a0-a2245777b432",
"Country": "US",
"State": "GA",
"StateName": "Georgia",
"CreatedDate": "2020-01-12T16:11:25.479Z"
},
"LatestSource": {
"DataSubjectId": "633ba071-61b0-485f-81a0-a2245777b432",
"ReceiptGuid": "633ba071-61b0-485f-81a0-a2245777b432",
"type": "WEB",
"content": "https://example.com/consent",
"CreatedDate": "2020-01-12T16:11:25.479Z"
}
}
],
"number": 1,
"size": 20
}