Skip to main content
PUT
/
retention_policies
/
{retention_policy_id}
cURL
curl -i -X PUT "https://api.box.com/2.0/retention_policies/982312" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "disposition_action": "permanently_delete"
     }'
{
  "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": "[email protected]"
  },
  "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": "[email protected]"
    }
  ],
  "assignment_counts": {
    "enterprise": 1,
    "folder": 1,
    "metadata_template": 1
  }
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
retention_policy_id
string
required

The ID of the retention policy.

Body

application/json
​
policy_name
string | null

The name for the retention policy.

Example:

"Some Policy Name"

​
description
string | null

The additional text description of the retention policy.

Example:

"Policy to retain all reports for at least one month"

​
disposition_action

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. You can use null if you don't want to change disposition_action.

Available options:
permanently_delete,
remove_retention
Example:

"permanently_delete"

​
retention_type
string | null

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.

When updating a retention policy, you can use non-modifiable type only. You can convert a modifiable policy to non-modifiable, but not the other way around.

Example:

"non-modifiable"

​
retention_length

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.

Example:

"365"

​
status
string | null

Used to retire a retention policy.

If not retiring a policy, do not include this parameter or set it to null.

Example:

"retired"

​
can_owner_extend_retention
boolean | null

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

Example:

false

​
are_owners_notified
boolean | null

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

Example:

false

​
custom_notification_recipients
User (Base) · object[] | null

A list of users notified when the retention duration is about to end.

Response

Returns the updated retention policy object.

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.

​
id
string
required

The unique identifier that represents a retention policy.

Example:

"12345"

​
type
enum<string>
required

The value will always be retention_policy.

Available options:
retention_policy
Example:

"retention_policy"

​
policy_name
string

The name given to the retention policy.

Example:

"Some Policy Name"

​
retention_length
string<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.

Example:

"365"

​
disposition_action
enum<string>

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
Example:

"permanently_delete"

​
description
string

The additional text description of the retention policy.

Example:

"Policy to retain all reports for at least one month"

​
policy_type
enum<string>

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
Example:

"finite"

​
retention_type
enum<string>

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
Example:

"non_modifiable"

​
status
enum<string>

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
Example:

"active"

​
created_by
User (Mini) · object

A mini user object representing the user that created the retention policy.

​
created_at
string<date-time>

When the retention policy object was created.

Example:

"2012-12-12T10:53:43-08:00"

​
modified_at
string<date-time>

When the retention policy object was last modified.

Example:

"2012-12-12T10:53:43-08:00"

​
can_owner_extend_retention
boolean

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

Example:

false

​
are_owners_notified
boolean

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

Example:

false

​
custom_notification_recipients
User (Mini) · object[]

A list of users notified when the retention policy duration is about to end.

​
assignment_counts
object

Counts the retention policy assignments for each item type.