---
title: "Search Data Subjects by Data Element"
method: POST
path: "/rest/api/consent/v4/datasubjects/search-by-element"
tags: ["Data Subjects V4"]
---

# Search Data Subjects by Data Element

`POST /rest/api/consent/v4/datasubjects/search-by-element`

## Request

- Base URL: `https://hostname`
- URL: `https://hostname/rest/api/consent/v4/datasubjects/search-by-element`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://{hostname}/api/access/v1/oauth/token` scopes: `CONSENT`

Use this API to search for data subjects based on a specific data element name and value.



> 🗒 Things to Know

> 

> - This API supports pagination with continuation tokens for large result sets.

## Request body

- ConsentAPIDataSubjectSearchByElementRequest
  - `dataElementName` string: Name of the data element to search by
  - `dataElementValue` string: Value of the data element to search for
  - `requestContinuation` string: Request continuation token for pagination

## Response `200`

Successfully retrieved data subjects matching the search criteria

- ConsentAPIDataSubjectSearchResponse
  - `data` ConsentAPIDataSubjectProfileDto[]
    - `language` string: The language set for the data subject.
    - `identifier` string: The data subject identifier of the data subject.
    - `linkToken` string: Token used for magic link authentication of the Data Subject
    - `createdDate` string, date-time: The date and time that the data subject record was created.
    - `testDataSubject` boolean: This flag indicates whether the data subject is used for testing purposes.
    - `id` string, uuid: Unique Identifier identifying a Data Subject
    - `lastUpdatedDate` string, date-time: The date that the Data Subject record was last updated on
    - `dataElements` ConsentAPIDataSubjectElementDto[]: The additional information about the data subject.
      - `name` string, required: The name of the data element.
      - `value` object: The value of the data element.
      - `linked` boolean: This flag indicates whether the data element is linked to the data subject.
    - `purposes` ConsentAPIDataSubjectProfilePurposeDto[]: List of purposes associated with the Data Subject's profile
      - `name` string: The Purpose name
      - `version` integer: Version of the Purpose
      - `status` string: The status of the purpose for the data subject.
      - `firstTransactionDate` string, date-time: The date and time that the first transaction was written to the database.
      - `lastTransactionDate` string, date-time: The date and time that the last transaction was written to the database.
      - `withdrawalDate` string, date-time: The date and time that the data subject withdrew consent for the purpose.
      - `expiryDate` string, date-time: The explicit expiration date after which the purpose is no longer valid and no further consent is collected against it.
      - `purposeNote` ConsentAPIPurposeNoteDto
        - `noteId` string, uuid: Unique identifier for the purpose note
        - `noteType` 'UNSUBSCRIBE_REASON': Type of the note
        - `noteLanguage` string: Language of the purpose note
        - `noteText` string: The actual text of the note
      - `lastUpdatedDate` string, date-time: The date and time of the latest change to the data subject profile in the database.to any of: Purpose version, Purpose Status, or Topic/Custom Preference selections
      - `lastInteractionDate` string, date-time: The date and time of the data subject's last interaction with the purpose.
      - `id` string, uuid: Unique Identifier identifying a Purpose
      - `lastReceiptId` string, uuid: Unique Identifier identifying a Receipt
      - `consentDate` string, date-time: The date and time that the data subject gave their last active consent.
      - `totalTransactionCount` integer: The total number of Transactions recorded against this Purpose
      - `lastTransactionCollectionPointId` string, uuid: Unique identifier of the collection point used in the last transaction
      - `lastTransactionCollectionPointVersion` integer: Version of the collection point used in the last transaction
  - `continuationToken` string

## Other responses

- `400`: Invalid request parameters or page size exceeds maximum limit
- `401`: Unauthorized access
- `403`: Insufficient permissions to perform data element search
- `422`: Missing or invalid data element name or value
- `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.dev/onetrust/apis/consent-preferences-universal-consent-preference-management.md) - [All operations](https://skmtc.dev/onetrust/apis/consent-preferences-universal-consent-preference-management/llms.txt) - [OpenAPI document](https://skmtc.dev/onetrust/apis/consent-preferences-universal-consent-preference-management/revisions/fe4a0697ec9d?raw)