File version retention

A retention policy blocks permanent deletion of content for a specified amount of time. Admins can apply policies to specified folders, or an entire enterprise. A file version retention is a record for a retained file version. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. For more information about retention policies, please visit our help documentation

string
11446498

The unique identifier for this file version retention.

string
file_version_retention

Value is always file_version_retention

string / date-time
2012-12-12T10:53:43-08:00

When this file version retention object was created

string / date-time
2012-12-12T10:53:43-08:00

When the retention expires on this file version retention

object

The file this file version retention was applied to

string
12345

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.

string
file

Value is always file

string
1

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.

The information about the current version of the file.

12345

The unique identifier that represent a file version.

file_version

Value is always file_version

134b65991ed521fcfe4724b7d814ab8ded5185dc

The SHA1 hash of this version of the file.

string
Contract.pdf

The name of the file

3

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.

string / digest
85136C79CBF9FE36BB9D05D0639C70C265C18D37

The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.

The file version this file version retention was applied to

12345

The unique identifier that represent a file version.

file_version

Value is always file_version

134b65991ed521fcfe4724b7d814ab8ded5185dc

The SHA1 hash of this version of the file.

The winning retention policy applied to this file version retention. A file version can have multiple retention policies applied.

12345

The unique identifier that represent a file version.

file_version

Value is always file_version

permanently_delete

The disposition action of the retention policy. This action can be permanently_delete, which will cause the content retained by the policy to be permanently deleted, or remove_retention, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired.

Value is one of permanently_delete,remove_retention

Some Policy Name

The name given to the retention policy

3651

The length of the retention policy. This length specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has A policy_type of indefinite, the retention_length will also be indefinite.

Response Example

{
  "id": 11446498,
  "type": "file_version_retention",
  "applied_at": "2012-12-12T10:53:43-08:00",
  "disposition_at": "2012-12-12T10:53:43-08:00",
  "file": {
    "id": 12345,
    "type": "file",
    "etag": 1,
    "file_version": {
      "id": 12345,
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "name": "Contract.pdf",
    "sequence_id": 3,
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37"
  },
  "file_version": {
    "id": 12345,
    "type": "file_version",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  },
  "winning_retention_policy": {
    "id": 12345,
    "type": "file_version",
    "disposition_action": "permanently_delete",
    "policy_name": "Some Policy Name",
    "retention_length": 365
  }
}