> ## 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

Use this API to search for data subjects based on various criteria. The response will include details for each matching data subject such as the associated data elements, data subject ID, and data subject identifier.

> 🗒 Things to Know
> 
> - This API supports complex search criteria including filtering by data elements, purposes, and consent status.
> - For large result sets, use pagination to retrieve data in manageable chunks.
> - The response can be customized using the properties parameter to include or exclude certain data.

> 🚧 
> 
> 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.

# 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 V2",
      "description": "The Data Subjects V2 APIs are used to manage data subjects using version 2 of the API.",
      "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 V2"
    }
  ],
  "paths": {
    "/api/consentmanager/v2/datasubjects/search": {
      "post": {
        "operationId": "searchDataSubjectsPostUsingPOST",
        "summary": "Search Data Subjects",
        "description": "Use this API to search for data subjects based on various criteria. The response will include details for each matching data subject such as the associated data elements, data subject ID, and data subject identifier.\n\n> 🗒 Things to Know\n> \n> - This API supports complex search criteria including filtering by data elements, purposes, and consent status.\n> - For large result sets, use pagination to retrieve data in manageable chunks.\n> - The response can be customized using the properties parameter to include or exclude certain data.\n\n> 🚧 \n> \n> 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.",
        "tags": [
          "Data Subjects V2"
        ],
        "x-onetrust": {
          "spec-label": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json"
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number (0-based).",
            "schema": {
              "type": "integer",
              "example": 0,
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Number of records per page (1-2000).",
            "schema": {
              "type": "integer",
              "example": 1000,
              "default": 1000,
              "maximum": 2000,
              "minimum": 1
            }
          },
          {
            "name": "isDNCInclude",
            "in": "query",
            "description": "Include Do Not Call list information (true/false).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectSearchDto"
              },
              "examples": {
                "Search by Email": {
                  "summary": "Find data subjects by email",
                  "description": "Search by Email",
                  "value": {
                    "dataElements": [
                      {
                        "name": "Email",
                        "value": "user@example.com"
                      }
                    ]
                  }
                },
                "Search by Purpose": {
                  "summary": "Find data subjects who consented to a specific purpose",
                  "description": "Search by Purpose",
                  "value": {
                    "purposeGuid": "550e8400-e29b-41d4-a716-446655440000",
                    "consentStatus": "GRANTED"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK - Search results returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectSliceDtoV2"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "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": [
          {
            "ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2": [
              "CONSENT",
              "CONSENT_READ"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ConsentPreferences-UniversalConsentPreferenceManag_PageableObject": {
        "properties": {
          "offset": {
            "type": "integer",
            "format": "int64"
          },
          "sort": {
            "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_SortObject"
          },
          "pageNumber": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          },
          "paged": {
            "type": "boolean"
          },
          "unpaged": {
            "type": "boolean"
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_SortObject": {
        "properties": {
          "empty": {
            "type": "boolean"
          },
          "unsorted": {
            "type": "boolean"
          },
          "sorted": {
            "type": "boolean"
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectElementSearchDto": {
        "properties": {
          "name": {
            "description": "The name of the data element to search for",
            "type": "string",
            "example": "Work Email"
          },
          "value": {
            "description": "The value to match against the specified data element name",
            "type": "string",
            "example": "example@otprivacy.com"
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectSearchDto": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Filter Data Subject records by GUID",
            "type": "string",
            "format": "uuid",
            "example": "2a95b8c1-e54f-49f0-906a-2f5880450999"
          },
          "identifier": {
            "description": "Filter Data Subject records by identifier (e.g., email, phone number)",
            "type": "string",
            "example": "example@otprivacy.com"
          },
          "updatedSince": {
            "description": "Filter Data Subject records updated on or after this date (format: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss)",
            "type": "string",
            "example": "2023-01-01T00:00:00"
          },
          "updatedUntil": {
            "description": "Filter Data Subject records updated on or before this date (format: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss)",
            "type": "string",
            "example": "2023-12-31T23:59:59"
          },
          "dataElements": {
            "description": "Filter Data Subject records by data elements with specific names and values",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectElementSearchDto"
            }
          },
          "language": {
            "description": "Filter Data Subject records by preferred language code",
            "type": "string",
            "example": "en-us"
          },
          "includeCounts": {
            "description": "When false, the response will not include the total record count (improves performance for large result sets)",
            "type": "boolean",
            "example": true,
            "default": true
          },
          "linkTokens": {
            "description": "When true, includes link tokens in the response for magic link functionality",
            "type": "boolean",
            "example": false,
            "default": false
          },
          "linkedDS": {
            "description": "When true, includes additional linked Data Subject information in the response",
            "type": "boolean",
            "example": false,
            "default": false
          },
          "ignoreDefaultSort": {
            "description": "When true, overrides the default sorting by last modified date",
            "type": "boolean",
            "example": false,
            "default": false
          },
          "orgIds": {
            "description": "Filter Data Subject records by organization IDs (internal use only)",
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "includeDataSubjectsWithOutPurposeTransactions": {
            "description": "When true, includes Data Subjects that don't have any purpose transactions",
            "type": "boolean",
            "example": false
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectDtoV2": {
        "properties": {
          "id": {
            "description": "Unique identifier for the Data Subject",
            "type": "string",
            "format": "uuid",
            "example": "633ba071-61b0-485f-81a0-a2245777b432"
          },
          "identifier": {
            "description": "The Data Subject's identifier (e.g., email, phone number)",
            "type": "string",
            "example": "example@otprivacy.com"
          },
          "language": {
            "description": "The preferred language code for the Data Subject",
            "type": "string",
            "example": "en-us"
          },
          "lastUpdatedDate": {
            "description": "The timestamp when the Data Subject's record was last updated",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-12T16:11:25.479Z"
          },
          "dataElements": {
            "description": "Map of data elements and their corresponding values for the Data Subject",
            "type": "object",
            "example": {
              "Title": "Mr",
              "FirstName": "Example"
            },
            "additionalProperties": true
          },
          "dataElementsMetaData": {
            "description": "List of data elements with metadata for the Data Subject",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectElementDtoV2"
            }
          },
          "linkToken": {
            "description": "Token used for magic link authentication of the Data Subject",
            "type": "string",
            "example": "jNJW2e8vm8eWb6DlWyGbZ/7PsfC+AHFN8JqvZHPGzJQ="
          },
          "createdDate": {
            "description": "The timestamp when the Data Subject's record was created",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-12T16:11:25.479Z"
          },
          "identifierType": {
            "description": "The type of identifier used for the Data Subject",
            "type": "string",
            "example": "Email"
          },
          "testDataSubject": {
            "description": "Indicates whether this is a test Data Subject",
            "type": "boolean",
            "example": false
          },
          "doNotCall": {
            "description": "Indicates if the Data Subject's phone number is on the FCC's Do Not Call list",
            "type": "boolean",
            "example": false
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectElementDtoV2": {
        "properties": {
          "name": {
            "description": "The name of the data element",
            "type": "string",
            "example": "Work Email"
          },
          "linked": {
            "description": "Indicates whether this data element value is linked as an identifier",
            "type": "boolean",
            "example": true
          },
          "value": {
            "description": "The value of the data element. Can be a single value or an array of values.",
            "type": "object",
            "example": "example@otprivacy.com"
          },
          "doNotCall": {
            "description": "Indicates if a phone number is listed in FCC's Do Not Call registry",
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "linked",
          "name",
          "value"
        ]
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectSliceDtoV2": {
        "type": "object",
        "properties": {
          "content": {
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectDtoV2"
            },
            "type": "array"
          },
          "number": {
            "description": "The page number of the results.",
            "type": "integer",
            "format": "int32",
            "example": 1
          },
          "size": {
            "description": "The number of results per page.",
            "type": "integer",
            "format": "int32",
            "example": 20
          },
          "pageable": {
            "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PageableObject"
          },
          "last": {
            "description": "Flag indicating whether this is the last page or not.",
            "type": "boolean",
            "example": false
          },
          "sort": {
            "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_SortObject"
          },
          "first": {
            "type": "boolean"
          },
          "numberOfElements": {
            "type": "integer",
            "format": "int32"
          },
          "empty": {
            "type": "boolean"
          }
        }
      }
    },
    "securitySchemes": {
      "ConsentPreferences-UniversalConsentPreferenceManag_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"
  }
}
```