---
title: "List file version legal holds"
method: GET
path: "/file_version_legal_holds"
tags: ["File version legal holds"]
---

# List file version legal holds

`GET /file_version_legal_holds`

Get a list of file versions on legal hold for a legal hold
assignment.

Due to ongoing re-architecture efforts this API might not return all file
versions for this policy ID.

Instead, this API will only return file versions held in the legacy
architecture. Two new endpoints will available to request any file versions
held in the new architecture.

For file versions held in the new architecture, the `GET
/legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to
return all past file versions available for this policy assignment, and the
`GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to
return any current (latest) versions of a file under legal hold.

The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to
find a list of policy assignments for a given policy ID.

Once the re-architecture is completed this API will be deprecated.

## Query parameters

- `policy_id` string, required
- `marker` string
- `limit` integer

## Response `200`

Returns the list of file version legal holds for a specific legal
hold policy.

- FileVersionLegalHolds — The part of an API response that describes marker based pagination.
  - `limit` integer — The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
  - `next_marker` string, nullable — The marker for the start of the next page of results.
  - `prev_marker` string, nullable — The marker for the start of the previous page of results.
  - `entries` FileVersionLegalHold[] — A list of file version legal holds.
    - `id` string — The unique identifier for this file version legal hold.
    - `type` 'file_version_legal_hold' — The value will always be `file_version_legal_hold`.
    - `file_version` object — The file version that is held.
      - `id` string, required — The unique identifier that represent a file version.
      - `type` 'file_version', required — The value will always be `file_version`.
      - `sha1` string — The SHA1 hash of this version of the file.
    - `file` object, nullable — The file for the file version held. Note that there is no guarantee that the current version of this file is held.
      - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.
      - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.
      - `type` 'file', required — The value will always be `file`.
      - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.
      - `name` string — The name of the file.
      - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
      - `file_version` object — The information about the current version of the file.
        - `id` string, required — The unique identifier that represent a file version.
        - `type` 'file_version', required — The value will always be `file_version`.
        - `sha1` string — The SHA1 hash of this version of the file.
    - `legal_hold_policy_assignments` LegalHoldPolicyAssignment[] — List of assignments contributing to this Hold.
      - `id` string — The unique identifier for this legal hold assignment.
      - `type` 'legal_hold_policy_assignment' — The value will always be `legal_hold_policy_assignment`.
      - `legal_hold_policy` object — The policy that the legal hold policy assignment is part of.
        - `id` string, required — The unique identifier for this legal hold policy.
        - `type` 'legal_hold_policy', required — The value will always be `legal_hold_policy`.
      - `assigned_to` object — The item that the legal hold policy is assigned to. Includes type and ID.
        - `type` 'file' | 'file_version' | 'folder' | 'user' | 'ownership' | 'interactions', required — The type of item the policy is assigned to.
        - `id` string, required — The ID of the item the policy is assigned to.
      - `assigned_by` object — The user who created the legal hold policy assignment.
        - `id` string, required — The unique identifier for this user.
        - `type` 'user', required — The value will always be `user`.
        - `name` string — The display name of this user.
        - `login` string, email — The primary email address of this user.
      - `assigned_at` string, date-time — When the legal hold policy assignment object was created.
      - `deleted_at` string, date-time — When the assignment release request was sent. (Because it can take time for an assignment to fully delete, this isn't quite the same time that the assignment is fully deleted). If null, Assignment was not deleted.
    - `deleted_at` string, date-time — Time that this File-Version-Legal-Hold was deleted.

## Other responses

- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)