Retention policies resources

A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then assign them to specific folders or their entire enterprise.

Retention policies

A list of retention policies.

Attributes and example

Property	Type	Required	Description
entries	array of Retention policy	No	A list in which each entry represents a retention policy object.
limit	integer	No	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	No	The marker for the start of the next page of results. Can be null.

Example

{
  "entries": [
    {
      "id": "12345",
      "type": "retention_policy",
      "policy_name": "Some Policy Name",
      "retention_length": "365",
      "disposition_action": "permanently_delete",
      "max_extension_length": "365",
      "description": "Policy to retain all reports for at least one month",
      "policy_type": "finite",
      "retention_type": "non_modifiable",
      "status": "active",
      "created_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "[e-mail]"
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "can_owner_extend_retention": false,
      "are_owners_notified": false,
      "custom_notification_recipients": [
        {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "[e-mail]"
        }
      ],
      "assignment_counts": {
        "enterprise": 1,
        "folder": 1,
        "metadata_template": 1
      }
    }
  ],
  "limit": 1000,
  "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
}

Retention policy

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.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier that represents a retention policy.
type	enum<string>	Yes	The value will always be retention_policy. Available options: retention_policy.
policy_name	string	No	The name given to the retention policy.
retention_length	string	No	The 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.
disposition_action	enum<string>	No	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. Available options: permanently_delete, remove_retention.
max_extension_length	Retention policy max extension length (response)	No	Available options: none.
description	string	No	The additional text description of the retention policy.
policy_type	enum<string>	No	The 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. Available options: finite, indefinite.
retention_type	enum<string>	No	Specifies 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. Available options: modifiable, non_modifiable.
status	enum<string>	No	The 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. Available options: active, retired.
created_by	User (Mini)	No	A mini user object representing the user that created the retention policy.
created_at	string	No	When the retention policy object was created.
modified_at	string	No	When the retention policy object was last modified.
can_owner_extend_retention	boolean	No	Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end.
are_owners_notified	boolean	No	Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end.
custom_notification_recipients	array of User (Mini)	No	A list of users notified when the retention policy duration is about to end.
assignment_counts	object	No	Counts the retention policy assignments for each item type.

Example

{
  "id": "12345",
  "type": "retention_policy",
  "policy_name": "Some Policy Name",
  "retention_length": "365",
  "disposition_action": "permanently_delete",
  "max_extension_length": "365",
  "description": "Policy to retain all reports for at least one month",
  "policy_type": "finite",
  "retention_type": "non_modifiable",
  "status": "active",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[e-mail]"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "can_owner_extend_retention": false,
  "are_owners_notified": false,
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "[e-mail]"
    }
  ],
  "assignment_counts": {
    "enterprise": 1,
    "folder": 1,
    "metadata_template": 1
  }
}

Retention policy (Base)

A base representation of a retention policy.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier that represents a retention policy.
type	enum<string>	Yes	The value will always be retention_policy. Available options: retention_policy.

Example

{
  "id": "12345",
  "type": "retention_policy"
}

Retention policy (Mini)

A mini representation of a retention policy, used when nested within another resource.

Attributes and example

Property	Type	Required	Description
id	string	Yes	The unique identifier that represents a retention policy.
type	enum<string>	Yes	The value will always be retention_policy. Available options: retention_policy.
policy_name	string	No	The name given to the retention policy.
retention_length	string	No	The 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.
disposition_action	enum<string>	No	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. Available options: permanently_delete, remove_retention.
max_extension_length	Retention policy max extension length (response)	No	Available options: none.

Example

{
  "id": "12345",
  "type": "retention_policy",
  "policy_name": "Some Policy Name",
  "retention_length": "365",
  "disposition_action": "permanently_delete",
  "max_extension_length": "365"
}