> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Data Subjects by Data Element

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.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Consent & Preferences - Universal Consent & Preference Management (OAS)",
    "version": "1.0",
    "contact": {
      "name": "OneTrust Support",
      "url": "https://my.onetrust.com/s/contactsupport"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "description": "The Universal Consent & Preference Management APIs are used to integrate external systems and streamline the flow of data with Universal Consent & Preference Management in the OneTrust Platform."
  },
  "servers": [
    {
      "url": "https://{hostname}",
      "variables": {
        "hostname": {
          "default": "hostname",
          "description": "The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com."
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Data Subjects V4",
      "description": "The Data Subjects V4 APIs are used to manage data subject information, preferences, and consent records.",
      "externalDocs": {
        "description": "OpenAPI 3.1.0 - Download Definition",
        "url": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json"
      },
      "x-displayName": "Data Subjects V4"
    }
  ],
  "paths": {
    "/rest/api/consent/v4/datasubjects/search-by-element": {
      "post": {
        "operationId": "searchDataSubjectsByElementV4",
        "summary": "Search Data Subjects by Data Element",
        "description": "Use this API to search for data subjects based on a specific data element name and value.\n\n> 🗒 Things to Know\n> \n> - This API supports pagination with continuation tokens for large result sets.",
        "tags": [
          "Data Subjects V4"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsentAPI_DataSubjectSearchByElementRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved data subjects matching the search criteria",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentAPI_DataSubjectSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters or page size exceeds maximum limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentAPI_DataSubjectSearchResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentAPI_DataSubjectSearchResponse"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions to perform data element search",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentAPI_DataSubjectSearchResponse"
                }
              }
            }
          },
          "422": {
            "description": "Missing or invalid data element name or value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentAPI_DataSubjectSearchResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "description": "The number of seconds after which requests will be allowed again.",
                  "format": "int32"
                }
              },
              "ot-period": {
                "schema": {
                  "description": "The unit of time for which the rate limit applies",
                  "enum": [
                    "HOUR",
                    "MINUTE"
                  ]
                }
              },
              "ot-ratelimit-event-id": {
                "schema": {
                  "description": "The unique identifier for the rate-limiting event.",
                  "format": "uuid"
                }
              },
              "ot-request-made": {
                "schema": {
                  "description": "The number of requests made within the specified period.",
                  "format": "int32"
                }
              },
              "ot-requests-allowed": {
                "schema": {
                  "description": "The number of requests allowed within the specified period.",
                  "format": "int32"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "ConsentAPI_OAUTH2": [
              "CONSENT"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ConsentAPI_DataSubjectElementDto": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The name of the data element.",
            "type": "string",
            "example": "Work Email"
          },
          "value": {
            "description": "The value of the data element.",
            "type": "object",
            "example": "example@otprivacy.com, [Red, Blue]"
          },
          "linked": {
            "description": "This flag indicates whether the data element is linked to the data subject.",
            "type": "boolean"
          }
        },
        "required": [
          "name"
        ]
      },
      "ConsentAPI_DataSubjectProfileDto": {
        "type": "object",
        "properties": {
          "language": {
            "description": "The language set for the data subject.",
            "type": "string",
            "example": "en-us"
          },
          "identifier": {
            "description": "The data subject identifier of the data subject.",
            "type": "string",
            "example": "example@otprivacy.com"
          },
          "linkToken": {
            "description": "Token used for magic link authentication of the Data Subject",
            "type": "string",
            "example": "jNJW2e8vm8eWb6DlWyGbZ/7PsfC+AHFN8JqvZHPGzJQ="
          },
          "createdDate": {
            "description": "The date and time that the data subject record was created.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-12T16:11:25.479Z"
          },
          "testDataSubject": {
            "description": "This flag indicates whether the data subject is used for testing purposes.",
            "type": "boolean",
            "example": true
          },
          "id": {
            "description": "Unique Identifier identifying a Data Subject",
            "type": "string",
            "format": "uuid",
            "example": "633ba071-61b0-485f-81a0-a2245777b432"
          },
          "lastUpdatedDate": {
            "description": "The date that the Data Subject record was last updated on",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-12T16:11:25.479Z"
          },
          "dataElements": {
            "description": "The additional information about the data subject.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentAPI_DataSubjectElementDto"
            }
          },
          "purposes": {
            "description": "List of purposes associated with the Data Subject's profile",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentAPI_DataSubjectProfilePurposeDto"
            }
          }
        }
      },
      "ConsentAPI_DataSubjectProfilePurposeDto": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The Purpose name",
            "type": "string",
            "example": "Marketing Communications"
          },
          "version": {
            "description": "Version of the Purpose",
            "type": "integer",
            "format": "int64",
            "example": 2
          },
          "status": {
            "description": "The status of the purpose for the data subject.",
            "type": "string",
            "example": "ACTIVE"
          },
          "firstTransactionDate": {
            "description": "The date and time that the first transaction was written to the database.",
            "type": "string",
            "format": "date-time",
            "example": "2020-02-12T13:56:32.621Z"
          },
          "lastTransactionDate": {
            "description": "The date and time that the last transaction was written to the database.",
            "type": "string",
            "format": "date-time",
            "example": "2020-02-12T14:22:09.801Z"
          },
          "withdrawalDate": {
            "description": "The date and time that the data subject withdrew consent for the purpose.",
            "type": "string",
            "format": "date-time",
            "example": "2020-02-12T13:59:00.045Z"
          },
          "expiryDate": {
            "description": "The explicit expiration date after which the purpose is no longer valid and no further consent is collected against it.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-07T13:57:03.012Z"
          },
          "purposeNote": {
            "description": "The details of the reason template used to explain changes to the data subject's preferences.",
            "$ref": "#/components/schemas/ConsentAPI_PurposeNoteDto"
          },
          "lastUpdatedDate": {
            "description": "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",
            "type": "string",
            "format": "date-time",
            "example": "2020-02-13T11:34:30.974Z"
          },
          "lastInteractionDate": {
            "description": "The date and time of the data subject's last interaction with the purpose.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-05T11:34:30.974Z"
          },
          "id": {
            "description": "Unique Identifier identifying a Purpose",
            "type": "string",
            "format": "uuid",
            "example": "369a7e44-ac23-4b50-a6a8-91c9e4aa3007"
          },
          "lastReceiptId": {
            "description": "Unique Identifier identifying a Receipt",
            "type": "string",
            "format": "uuid",
            "example": "057f47e6-dc7a-47da-a1d3-5b17b5c75e54"
          },
          "consentDate": {
            "description": "The date and time that the data subject gave their last active consent.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-07T13:18:23.123Z"
          },
          "totalTransactionCount": {
            "description": "The total number of Transactions recorded against this Purpose",
            "type": "integer",
            "format": "int64",
            "example": 3
          },
          "lastTransactionCollectionPointId": {
            "description": "Unique identifier of the collection point used in the last transaction",
            "type": "string",
            "format": "uuid"
          },
          "lastTransactionCollectionPointVersion": {
            "description": "Version of the collection point used in the last transaction",
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "ConsentAPI_DataSubjectSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentAPI_DataSubjectProfileDto"
            }
          },
          "continuationToken": {
            "type": "string"
          }
        }
      },
      "ConsentAPI_PurposeNoteDto": {
        "type": "object",
        "properties": {
          "noteId": {
            "description": "Unique identifier for the purpose note",
            "type": "string",
            "format": "uuid",
            "example": "d1a8f6f2-781a-4b2b-b1db-07e25f1c9a94"
          },
          "noteType": {
            "description": "Type of the note",
            "type": "string",
            "enum": [
              "UNSUBSCRIBE_REASON"
            ]
          },
          "noteLanguage": {
            "description": "Language of the purpose note",
            "type": "string",
            "example": "en-us"
          },
          "noteText": {
            "description": "The actual text of the note",
            "type": "string",
            "example": "0e7ed8b7-a64d-4e38-a7ea-7c28dbdd5869"
          }
        }
      },
      "ConsentAPI_DataSubjectSearchByElementRequest": {
        "type": "object",
        "properties": {
          "dataElementName": {
            "description": "Name of the data element to search by",
            "type": "string",
            "example": "Email",
            "minLength": 1
          },
          "dataElementValue": {
            "description": "Value of the data element to search for",
            "type": "string",
            "example": "test@example.com",
            "minLength": 1
          },
          "requestContinuation": {
            "description": "Request continuation token for pagination",
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ConsentAPI_OAUTH2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{hostname}/api/access/v1/oauth/token",
            "scopes": {
              "CONSENT": "Consent Scope gives the user access to read/write operations",
              "CONSENT_READ": "Consent Read Scope gives the user read-only access"
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "metrics-enabled": false
  },
  "x-onetrust": {
    "spec-label": "OpenAPI 3.1.0"
  }
}
```