---
title: "Get List of Data Subjects by Purpose"
method: GET
path: "/api/consentmanager/v1/purposes/{purposeId}/datasubjects"
tags: ["Purposes"]
---

# Get List of Data Subjects by Purpose

`GET /api/consentmanager/v1/purposes/{purposeId}/datasubjects`

Use this API to retrieve a list of data subjects by Purpose. The response will include details for each data subject such as the last transaction date, the transaction status for that Purpose, and Purpose Preferences they have interacted with.

> 🗒 Things to Know
> 
> - This API can be used as an alternative to the [Get List of Data Subjects](https://developer.onetrust.com/onetrust/reference/getdatasubjectprofileusingget) API when data subject records for a specific Purpose are required.
> - This API returns Purpose descriptions inside `<p>` and `</p> `HTML tags. These can be sanitized depending on your formatting needs.

## Path parameters

- `purposeId` string, uuid, required

## Query parameters

- `lastTransactionDate` string, date-time
- `transactionStatus` 'ACTIVE' | 'WITHDRAWN' | 'EXPIRED'
- `includeCustomPreferences` boolean

## Response `200`

OK - Successfully retrieved data subjects for purpose

- ConsentPreferencesUniversalConsentPreferenceManagPageDataSubjectForPurposeInformation
  - `content` ConsentPreferencesUniversalConsentPreferenceManagDataSubjectForPurposeInformation[] — The list of items for the current page.
    - `DataSubjectId` string, required — Unique identifier of the Data Subject (typically an email or ID)
    - `Status` 'ACTIVE' | 'WITHDRAWN' | 'EXPIRED' | 'NOT GIVEN' | 'PENDING' | 'OPT OUT', required — Current transaction status of the Data Subject for this Purpose
    - `FirstTransactionDate` string, date-time — Timestamp of the first transaction for this Data Subject and Purpose
    - `LastTransactionDate` string, date-time — Timestamp of the most recent transaction for this Data Subject and Purpose
    - `Topics` ConsentPreferencesUniversalConsentPreferenceManagTopicInformation[] — List of topics associated with the Data Subject's consent
      - `Id` string, uuid
      - `Name` string
    - `CustomPreferences` ConsentPreferencesUniversalConsentPreferenceManagCustomPreferenceInformation[] — List of custom preferences selected by the Data Subject
      - `Id` string, uuid, required — Unique identifier of the custom preference
      - `Name` string, required — Display name of the custom preference
      - `CustomPreferenceOptions` ConsentPreferencesUniversalConsentPreferenceManagCustomPreferenceOptionsInformation[] — List of options selected by the data subject for this custom preference
        - `Id` string, uuid, required — Unique identifier of the custom preference option
        - `Name` string, required — Display name of the custom preference option
  - `empty` boolean — The flag to check if the entity is empty or not.
  - `first` boolean — The flag to check if the entity is first entity or not.
  - `last` boolean — The flag to check if the entity is last entity or not.
  - `number` integer — The number associated with the result.
  - `numberOfElements` integer — Total number of elements in the result.
  - `pageable` ConsentPreferencesUniversalConsentPreferenceManagPageableObject
    - `offset` integer
    - `sort` ConsentPreferencesUniversalConsentPreferenceManagSortObject
      - `empty` boolean
      - `unsorted` boolean
      - `sorted` boolean
    - `pageNumber` integer
    - `pageSize` integer
    - `paged` boolean
    - `unpaged` boolean
  - `sort` ConsentPreferencesUniversalConsentPreferenceManagSortObject
    - `empty` boolean
    - `unsorted` boolean
    - `sorted` boolean
  - `totalPages` integer — Total number of pages in the result list.
  - `totalElements` integer — Total number of elements in the result.
  - `size` integer — Size of the result list.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests. For more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).
- `500` — Internal Server Error

---

[API](https://skmtc.net/onetrust/apis/platform-access-management.md) · [All operations](https://skmtc.net/onetrust/apis/platform-access-management/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onetrust/platform-access-management/revisions/21de3aa0b170/schema)