Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

List file version legal holds

get
https://api.box.com/2.0
/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.

Request

bearer [ACCESS_TOKEN]
application/json

Query Parameters

integer (int64)in queryoptional
10001000

The maximum number of items to return per page.

stringin queryoptional
JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii

Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.

This requires usemarker to be set to true.

stringin queryrequired
133870

The ID of the legal hold policy to get the file version legal holds for.

Response

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

application/jsonClient error

An unexpected client error.

get
List file version legal holds
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X GET "https://api.box.com/2.0/file_version_legal_holds?policy_id=133870" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
TypeScript Gen
await client.fileVersionLegalHolds.getFileVersionLegalHolds({
  policyId: policyId,
} satisfies GetFileVersionLegalHoldsQueryParams);
Python Gen
client.file_version_legal_holds.get_file_version_legal_holds(policy_id)
.NET Gen
await client.FileVersionLegalHolds.GetFileVersionLegalHoldsAsync(queryParams: new GetFileVersionLegalHoldsQueryParams(policyId: policyId));
Swift Gen (Beta)
try await client.fileVersionLegalHolds.getFileVersionLegalHolds(queryParams: GetFileVersionLegalHoldsQueryParams(policyId: policyId))
Java
BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, id);
Iterable<BoxFileVersionLegalHold.Info> fileVersionHolds = policy.getFileVersionHolds();
for (BoxFileVersionLegalHold.Info fileVersionHold : fileVersionHolds) {
	// Do something with the file version legal hold.
}
Python
legal_holds = client.legal_hold_policy(policy_id='12345').get_file_version_legal_holds()
for legal_hold in legal_holds:
    print(f'Got file version legal hold with ID {legal_hold.id}')
.NET
BoxCollectionMarkerBased<BoxFileVersionLegalHold> holds = await client.LegalHoldPoliciesManager
    .GetFileVersionLegalHoldsAsync(policyId: "11111");
Node
client.legalHoldPolicies.getAllFileVersionLegalHolds('11111')
	.then(holds => {
		/* holds -> {
			entries: 
			[ { type: 'legal_hold', id: '22222' },
				{ type: 'legal_hold', id: '33333' },
				{ type: 'legal_hold', id: '44444' } ],
			limit: 100,
			order: 
			[ { by: 'retention_policy_set_id, file_version_id',
				direction: 'ASC' } ] }
		*/
	});
iOS
let iterator = client.legalHolds.listFileVersionPolicies(policyId: "1234")
iterator.next { result in
    switch results {
    case let .success(page):
        for hold in page.entries {
            print("Legal hold \(hold.id)")
        }

    case let .failure(error):
        print(error)
    }
}

Response Example

{
  "entries": [
    {
      "id": "11446498",
      "type": "file_version_legal_hold",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      },
      "file": {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      },
      "legal_hold_policy_assignments": [
        {
          "id": "11446498",
          "type": "legal_hold_policy_assignment",
          "legal_hold_policy": {
            "id": "11446498",
            "type": "legal_hold_policy"
          },
          "assigned_to": {
            "id": "12345",
            "etag": "1",
            "type": "file",
            "sequence_id": "3",
            "name": "Contract.pdf",
            "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
            "file_version": {
              "id": "12345",
              "type": "file_version",
              "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
            },
            "description": "Contract for Q1 renewal",
            "size": 629644,
            "path_collection": {
              "total_count": 1,
              "entries": [
                {
                  "id": "12345",
                  "etag": "1",
                  "type": "folder",
                  "sequence_id": "3",
                  "name": "Contracts"
                }
              ]
            },
            "created_at": "2012-12-12T10:53:43-08:00",
            "modified_at": "2012-12-12T10:53:43-08:00",
            "trashed_at": "2012-12-12T10:53:43-08:00",
            "purged_at": "2012-12-12T10:53:43-08:00",
            "content_created_at": "2012-12-12T10:53:43-08:00",
            "content_modified_at": "2012-12-12T10:53:43-08:00",
            "created_by": {
              "id": "11446498",
              "type": "user",
              "name": "Aaron Levie",
              "login": "ceo@example.com"
            },
            "modified_by": {
              "id": "11446498",
              "type": "user",
              "name": "Aaron Levie",
              "login": "ceo@example.com"
            },
            "owned_by": {
              "id": "11446498",
              "type": "user",
              "name": "Aaron Levie",
              "login": "ceo@example.com"
            },
            "shared_link": {
              "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
              "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
              "vanity_url": "https://acme.app.box.com/v/my_url/",
              "vanity_name": "my_url",
              "access": "open",
              "effective_access": "company",
              "effective_permission": "can_download",
              "unshared_at": "2018-04-13T13:53:23-07:00",
              "is_password_enabled": true,
              "permissions": {
                "can_download": true,
                "can_preview": true,
                "can_edit": false
              },
              "download_count": 3,
              "preview_count": 3
            },
            "parent": {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            },
            "item_status": "active"
          },
          "assigned_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "assigned_at": "2012-12-12T10:53:43-08:00",
          "deleted_at": "2012-12-12T10:53:43-08:00"
        }
      ],
      "deleted_at": "2012-12-12T10:53:43-08:00"
    }
  ],
  "limit": 1000,
  "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
  "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih"
}