Assign retention policy


Assigns a retention policy to an item.



Request Body

objectin body

The item to assign the policy to

stringin bodyrequired

The ID of item to assign the policy to.

Set to null or omit when type is set to enterprise.

stringin bodyrequired

The type of item to assign the policy to.

Value is one of "enterprise", "folder", "metadata_template"

stringin bodyrequired

The ID of the retention policy to assign


Returns a new retention policy assignment object.

application/jsonClient Error

Returns an error if an id is specified while assigning a the retention policy to an enterprise.

application/jsonClient Error

Returns an error if no retention policy with the given policy_id exists.

application/jsonClient Error

Returns an error if a retention policy of equal or greater length has already been assigned to this item.

You can now try out some of our APIs live, right here in the documentation.
Log In

Request Example

curl -X POST \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "policy_id": "173463",
       "assign_to": {
         "type": "folder",
         "id": "6564564"
var assignmentParams = new BoxRetentionPolicyAssignmentRequest()
    PolicyId = "11111",
    AssignTo = new BoxRequestEntity()
        Type = BoxType.folder,
        Id = "22222"
BoxRetentionPolicyAssignment assignment = await client.RetentionPoliciesManager
// Assign the policy to the entire enterprise
BoxRetentionPolicy policy = new BoxRetentionPolicy(api, policyID);
BoxRetentionPolicyAssignment.Info enterpriseAssignmentInfo = policy.assignToEnterprise();

// Assign the policy to a single folder
BoxFolder folder = new BoxFolder(api, folderID);
BoxRetentionPolicyAssignment.Info folderAssignmentInfo = policy.assignTo(folder);

// Assign the policy to all items with metadata template "f0dce190-8106-43ca-9d67-7dce9b10a55e"
BoxRetentionPolicyAssignment.Info metadataAssignmentInfo = policy.assignToMetadataTemplate("f0dce190-8106-43ca-9d67-7dce9b10a55e");
folder = client.folder(folder_id='1111')
assignment = client.retention_policy(policy_id='12345').assign(folder)
print('Assignment ID is {0} and it is assigned by {1}'.format(,
client.retentionPolicies.assign('11111', 'folder', '22222')
	.then(assignment => {
		/* assignment -> {
			type: 'retention_policy_assignment',
			id: '12345',
			{ type: 'retention_policy',
				id: '11111',
				policy_name: 'Tax Documents' },
			assigned_to: { type: 'folder', id: '22222' },
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: '' },
			assigned_at: '2015-07-20T14:28:09-07:00' }

Response Example

  "id": 11446498,
  "type": "retention_policy_assignment",
  "retention_policy": {
    "id": 12345,
    "type": "file_version",
    "policy_name": "Some Policy Name",
    "retention_length": 0,
    "disposition_action": "permanently_delete"
  "assigned_to": {
    "id": 11446498
  "assigned_by": {
    "id": 11446498,
    "type": "user",
    "name": "Aaron Levie",
    "login": ""
  "assigned_at": "2012-12-12T10:53:43-08:00"