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

# 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 the associated data elements, data subject ID, and data subject identifier. By default, the response will return data subject details sorted in descending order of last modified date.

> 🗒 Things to Know
> 
> - This API is not designed to be used in synchronous workflows. As an alternative, the [Gets preferences for a Data Subject](https://developer.onetrust.com/onetrust/reference/getpreferencesusingget) API can be called.

> 🚧 
> 
> 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": {
      "get": {
        "operationId": "getDataSubjectsUsingGET",
        "summary": "Get List of Data Subjects",
        "description": "Use this API to retrieve a list of all data subjects. The response will include details for each data subject such as the associated data elements, data subject ID, and data subject identifier. By default, the response will return data subject details sorted in descending order of last modified date.\n\n> 🗒 Things to Know\n> \n> - This API is not designed to be used in synchronous workflows. As an alternative, the [Gets preferences for a Data Subject](https://developer.onetrust.com/onetrust/reference/getpreferencesusingget) API can be called.\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-50).",
            "schema": {
              "type": "integer",
              "example": 20,
              "default": 20,
              "maximum": 2000,
              "minimum": 1
            }
          },
          {
            "name": "updatedSince",
            "in": "query",
            "description": "Filter Data Subject records that were last updated on or after the specified date. Formats accepted: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2023-01-01T00:00:00"
            }
          },
          {
            "name": "updatedUntil",
            "in": "query",
            "description": "Filter Data Subject records that were last updated on or before the specified date. Must be used with updatedSince. Formats accepted: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2023-12-31T23:59:59"
            }
          },
          {
            "name": "identifier",
            "in": "header",
            "description": "Filter by data subject identifier (prefer using the header parameter).",
            "schema": {
              "type": "string",
              "example": "user@example.com"
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filter by data subject ID (UUID).",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "a9adf402-adcd-45be-b981-a56a5c0739ec"
            }
          },
          {
            "name": "dataElementName",
            "in": "header",
            "description": "Filter by data element name (must be used with dataElementValue).",
            "schema": {
              "type": "string",
              "example": "Email"
            }
          },
          {
            "name": "dataElementValue",
            "in": "header",
            "description": "Filter by data element value (must be used with dataElementName).",
            "schema": {
              "type": "string",
              "example": "user@example.com"
            }
          },
          {
            "name": "language",
            "in": "query",
            "description": "Filter by language code (e.g., 'en', 'fr').",
            "schema": {
              "type": "string",
              "example": "en"
            }
          },
          {
            "name": "properties",
            "in": "query",
            "description": "Specify optional properties to control the response. Multiple values can be comma-separated.\n\n- `ignoreCount`: Skip the total record count calculation (improves performance)\n- `linkTokens`: Include link tokens in the response\n- `ignoreDefaultSort`: Disable default sorting by last modified date",
            "schema": {
              "type": "string",
              "example": "ignoreCount,linkTokens"
            }
          },
          {
            "name": "includeDataSubjectsWithOutPurposeTransactions",
            "in": "query",
            "description": "Include data subjects without purpose transactions (true/false).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "isDNCInclude",
            "in": "query",
            "description": "Include Do Not Call list information (true/false).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK - List of data subjects retrieved 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_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"
  }
}
```