v1

latestOpenAPI 3.0.2Apache-2.02026-07-142963051.0 MB

Retention policies

Create retention policy

Creates a retention policy.

post/retention_policies

Request body

policy_namestring required

The name for the retention policy.

descriptionstring

The additional text description of the retention policy.

policy_type'finite' | 'indefinite' required

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.

disposition_action'permanently_delete' | 'remove_retention' required

The disposition action of the retention policy. permanently_delete deletes the content retained by the policy permanently. remove_retention lifts retention policy from the content, allowing it to be deleted by users once the retention policy has expired.

retention_type'modifiable' | 'non_modifiable'

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.

can_owner_extend_retentionboolean

Whether the owner of a file will be allowed to extend the retention.

are_owners_notifiedboolean

Whether owner and co-owners of a file are notified when the policy nears expiration.

Example request

{
  "policy_name": "Some Policy Name",
  "description": "Policy to retain all reports for at least one month",
  "policy_type": "finite",
  "disposition_action": "permanently_delete",
  "retention_type": "modifiable",
  "can_owner_extend_retention": true,
  "are_owners_notified": true,
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    }
  ]
}

Response

Returns a new retention policy object.

idstring required

The unique identifier that represents a retention policy.

type'retention_policy' required

The value will always be retention_policy.

policy_namestring

The name given to the retention policy.

retention_lengthstring int32

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'permanently_delete' | 'remove_retention'

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.

descriptionstring

The additional text description of the retention policy.

policy_type'finite' | 'indefinite'

retention_type'modifiable' | 'non_modifiable'

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.

status'active' | 'retired'

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.

created_atstring date-time

When the retention policy object was created.

modified_atstring date-time

When the retention policy object was last modified.

can_owner_extend_retentionboolean

Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end.

are_owners_notifiedboolean

Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end.

Example response

{
  "id": "12345",
  "type": "retention_policy",
  "policy_name": "Some Policy Name",
  "retention_length": "365",
  "disposition_action": "permanently_delete",
  "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": "ceo@example.com"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    }
  ],
  "assignment_counts": {
    "enterprise": 1,
    "folder": 1,
    "metadata_template": 1
  }
}