> 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/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` since there are more results to retrieve when `nextToken` is defined.

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

```typescript
try {
  let nextToken: string | undefined = undefined
  do {
    const listOutput = await privacyInteractionClient.listDataHolders({
      virtualPresenceId: 'virtual-presence-id',
      limit: 20,
      nextToken,
    })

    for (const dataHolder of listOutput.items) {
      console.log(dataHolder.name, dataHolder.protectionState)
    }

    nextToken = listOutput.nextToken
  } while (nextToken !== undefined)
} 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](https://docs.sudoplatform.com/~/revisions/U8P5YQbTWlABRqHUlUfP/guides/privacy-interaction/subscriptions).