Skip to main content
A retention policy blocks permanent deletion of content for a specified amount of time. A file version retention is a record for a retained file.

​
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 in your application management console. Note: File retention API is now deprecated. To get information about files and file versions under retention, see files under retention or file versions under retention endpoints.
PropertyTypeRequiredDescription
idstringNoThe unique identifier for this file version retention.
typeenum<string>NoThe value will always be file_version_retention. Available options: file_version_retention.
file_versionFile version (Mini)NoThe file version this file version retention was applied to.
fileFile (Mini)NoThe file this file version retention was applied to.
applied_atstringNoWhen this file version retention object was created.
disposition_atstringNoWhen the retention expires on this file version retention.
winning_retention_policyRetention policy (Mini)NoThe winning retention policy applied to this file version retention. A file version can have multiple retention policies applied.
Example
{
  "id": "11446498",
  "type": "file_version_retention",
  "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"
    }
  },
  "applied_at": "2012-12-12T10:53:43-08:00",
  "disposition_at": "2012-12-12T10:53:43-08:00",
  "winning_retention_policy": {
    "id": "12345",
    "type": "retention_policy",
    "policy_name": "Some Policy Name",
    "retention_length": "365",
    "disposition_action": "permanently_delete",
    "max_extension_length": "365"
  }
}

​
File version retentions

A list of file version retentions. Note: File retention API is now deprecated. To get information about files and file versions under retention, see files under retention or file versions under retention endpoints.
PropertyTypeRequiredDescription
limitintegerNoThe 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_markerstringNoThe marker for the start of the next page of results. Can be null.
prev_markerstringNoThe marker for the start of the previous page of results. Can be null.
entriesarray of File version retentionNoA list of file version retentions.
Example
{
  "limit": 1000,
  "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
  "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
  "entries": [
    {
      "id": "11446498",
      "type": "file_version_retention",
      "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"
        }
      },
      "applied_at": "2012-12-12T10:53:43-08:00",
      "disposition_at": "2012-12-12T10:53:43-08:00",
      "winning_retention_policy": {
        "id": "12345",
        "type": "retention_policy",
        "policy_name": "Some Policy Name",
        "retention_length": "365",
        "disposition_action": "permanently_delete",
        "max_extension_length": "365"
      }
    }
  ]
}
Last modified on July 9, 2026