Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Update retention policy

put
https://api.box.com/2.0
/retention_policies/:retention_policy_id

Updates a retention policy.

Request

bearer [ACCESS_TOKEN]
application/json

Path Parameters

stringin pathrequired
982312

The ID of the retention policy.

Request Body

booleanin bodyoptional
false

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

booleanin bodyoptional
false

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

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

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

The additional text description of the retention policy.

string objectin body
"permanently_delete"

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.

stringin bodyoptional
"Some Policy Name"

The name for the retention policy

string (int32) / number (int32) in body
"365"

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.

stringin bodyoptional
"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.

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.

stringin bodyoptional
"retired"

Used to retire a retention policy.

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

Response

application/jsonRetention policy

Returns the updated retention policy object.

application/jsonClient error

Returns a bad_request if an incorrect disposition_action was set or description exceeds maximum length of 500 characters.

application/jsonClient error

Returns an error when a user wants to shorten the duration of a non-modifiable policy, or to convert a non-modifiable policy to a modifiable one. Note: Lengthening policy duration is allowed.

application/jsonClient error

Returns an error if a retention policy with the given name already exists

application/jsonClient error

An unexpected client error.

put
Update retention policy
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

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"
     }'
TypeScript Gen
await client.retentionPolicies.updateRetentionPolicyById(retentionPolicy.id, {
  requestBody: {
    policyName: updatedRetentionPolicyName,
  } satisfies UpdateRetentionPolicyByIdRequestBody,
} satisfies UpdateRetentionPolicyByIdOptionalsInput);
Python Gen
client.retention_policies.update_retention_policy_by_id(
    retention_policy.id, policy_name=updated_retention_policy_name
)
.NET Gen
await client.RetentionPolicies.UpdateRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id, requestBody: new UpdateRetentionPolicyByIdRequestBody() { PolicyName = updatedRetentionPolicyName });
Java
BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id);
BoxRetentionPolicy.Info policyInfo = policy.new Info();
policyInfo.setPolicyName("new policy name");
policy.updateInfo(policyInfo);
Python
policy_update = {'policy_name': 'New Policy Name',}
updated_retention_policy = client.retention_policy(retention_id='12345').update_info(data=policy_update)
print(f'Retention Policy ID is {updated_retention_policy.id} and the new policy name is {updated_retention_policy.policy_name}')
.NET
var updates = new BoxRetentionPolicyRequest()
{
    PolicyName = "New Policy Name"
};
BoxRetentionPolicy updatedPolicy = await client.RetentionPoliciesManager
    .UpdateRetentionPolicyAsync("11111", updates);
Node
client.retentionPolicies
	.update('123456789', { status: 'retired' })
	.then((policy) => {
		/* policy -> {
			type: 'retention_policy',
			id: '123456789',
			policy_name: 'Tax Documents',
			policy_type: 'indefinite',
			retention_length: 'indefinite',
			retention_type: 'modifiable',
			description: 'Policy to retain all reports',
			disposition_action: 'remove_retention',
			can_owner_extend_retention: false,
			status: 'retired',
			are_owners_notified: true,
			custom_notification_recipients: []
			assignment_counts: { enterprise: 0, folder: 1, metadata_template: 0 },
			created_by:
			{ type: 'user',
				id: '11111',
				name: 'Example User',
				login: 'user@example.com' },
			created_at: '2015-05-01T11:12:54-07:00',
			modified_at: '2015-06-08T11:11:50-07:00' }
		*/
	});
iOS
client.retentionPolicy.update(policyId: "1234", name: "New Policy Name") { result in
    guard case let .success(retentionPolicy) = result else {
        print("Error updating a retention policy")
        return
    }
    
    print("Updated retention policy: \(retentionPolicy.id)")
}

Response Example

{
  "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": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    }
  ],
  "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"
}