Skip to main content
API version 2024.0 A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders, metadata templates, or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console.
This resource has a few variations that can be encountered when using the API.The fields that are part of the standard variant are generally returned when the resource is requested via its own API endpoints. For example, when retrieving a file by ID, it will return these fields unless the fields parameter has been specified.
​
id
string
example: 12345The unique identifier that represents a retention policy.
​
type
string
example: retention_policyThe value will always be retention_policy.Value is always retention_policy
​
are_owners_notified
boolean
example: falseDetermines if owners and co-owners of items under the policy are notified when the retention duration is about to end.
​
assignment_counts
object
Counts the retention policy assignments for each item type.
​
can_owner_extend_retention
boolean
example: falseDetermines if the owner of items under the policy can extend the retention when the original retention duration is about to end.
​
created_at
string(date-time)
example: 2012-12-12T10:53:43-08:00When the retention policy object was created.
​
created_by
User (Mini)object
A mini user object representing the user that created the retention policy.
​
custom_notification_recipients
User (Mini)array
A list of users notified when the retention policy duration is about to end.
​
description
string
example: Policy to retain all reports for at least one monthThe additional text description of the retention policy.
​
disposition_action
string
example: permanently_deleteThe 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
​
modified_at
string(date-time)
example: 2012-12-12T10:53:43-08:00When the retention policy object was last modified.
​
policy_name
string
example: Some Policy NameThe name given to the retention policy.
​
policy_type
string
example: finiteThe type of the retention policy. A retention policy type can either be finite, where a specific amount of time to retain the content is known upfront, or indefinite, where the amount of time to retain the content is still unknown.Value is one of finite,indefinite
​
retention_length
string(int32)
example: 365The length of the retention policy. This value 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.
​
retention_type
string
example: non_modifiableSpecifies the retention type:
  • modifiable: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes.
  • non-modifiable: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies.
Value is one of modifiable,non_modifiable
​
status
string
example: activeThe status of the retention policy. The status of a policy will be active, unless explicitly retired by an administrator, in which case the status will be retired. Once a policy has been retired, it cannot become active again.Value is one of active,retired
{
  "id": "12345",
  "type": "retention_policy",
  "are_owners_notified": false,
  "assignment_counts": {
    "enterprise": 1,
    "folder": 1,
    "metadata_template": 1
  },
  "can_owner_extend_retention": false,
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "login": "[email protected]",
    "name": "Aaron Levie"
  },
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "login": "[email protected]",
      "name": "Aaron Levie"
    }
  ],
  "description": "Policy to retain all reports for at least one month",
  "disposition_action": "permanently_delete",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "policy_name": "Some Policy Name",
  "policy_type": "finite",
  "retention_length": "365",
  "retention_type": "non_modifiable",
  "status": "active"
}