> For the complete documentation index, see [llms.txt](https://docs.sudoplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sudoplatform.com/~/revisions/U8P5YQbTWlABRqHUlUfP/guides/privacy-interaction/manage-data-holders.md).

# Manage Data Holders

Data holders represent entities such as online retailers, social media platforms, or SaaS services that have interacted with the user's email account or other online presence.

### Retrieving a Data Holder <a href="#retrieving-a-data-holder" id="retrieving-a-data-holder"></a>

To retrieve a single data holder by its unique identifier, use the `getDataHolder` method. This will return the data holder if it exists, or `undefined` if not found.

{% tabs %}
{% tab title="Typescript" %}

```typescript
try {
  const dataHolder = await privacyInteractionClient.getDataHolder(dataHolderId)
  if (dataHolder) {
    // Data holder found.
    console.log(dataHolder.name, dataHolder.domainName)
  } else {
    // No data holder with this ID exists.
  }
} catch (error) {
  // Handle/notify user of errors
}
```

{% endtab %}
{% endtabs %}

### Listing Data Holders <a href="#listing-data-holders" id="listing-data-holders"></a>

To retrieve all data holders associated with a specific virtual presence, use the `listDataHolders` method. Results are paginated.

A call to `listDataHolders` returns a `ListOutput` object containing a list of matching `items` and a `nextToken` to support pagination. If no results are found, the result will contain empty items. Always check the value of the returned `nextToken`—there are no more results to retrieve when `nextToken` is undefined.

{% tabs %}
{% tab title="Typescript" %}

```typescript
try {
  const listOutput = await privacyInteractionClient.listDataHolders({
    virtualPresenceId: 'virtual-presence-id',
    limit: 20,
    nextToken: undefined,
  })
  // `listOutput.items` contains the data holders.
  // Page through results if `listOutput.nextToken` is defined.
  for (const dataHolder of listOutput.items) {
    console.log(dataHolder.name, dataHolder.protectionState)
  }
} catch (error) {
  // Handle/notify user of errors
}
```

{% endtab %}
{% endtabs %}

**Input Parameters:**

| Parameter           | Type   | Required | Description                                                      |
| ------------------- | ------ | -------- | ---------------------------------------------------------------- |
| `virtualPresenceId` | string | Yes      | The identifier of the virtual presence to list data holders for. |
| `limit`             | number | No       | Maximum number of items to return. Will be defaulted if omitted. |
| `nextToken`         | string | No       | A pagination token from a previous call.                         |

### Data Holder Protection States <a href="#data-holder-protection-states" id="data-holder-protection-states"></a>

Each data holder has a protection state indicating its current status in the monitoring lifecycle:

| State              | Description                                                                     |
| ------------------ | ------------------------------------------------------------------------------- |
| `MONITORED`        | The data holder is being actively monitored for privacy changes.                |
| `ACTION_REQUESTED` | An action (e.g., deletion request) has been initiated against this data holder. |
| `RESOLVED`         | The data holder interaction has been resolved.                                  |

### Subscribing to Data Holder Updates <a href="#subscribing-to-data-holder-updates" id="subscribing-to-data-holder-updates"></a>

To receive real-time notifications when data holders are discovered or updated during scanning, see [Subscriptions](file:///Users/jkowald/source/repos/sudo-privacy-interaction-js/docs/guides/privacy-interaction/subscriptions.md).