Box Developer Documentation

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

Register now!

Assign retention policy

post
https://api.box.com/2.0
/retention_policy_assignments

Assigns a retention policy to an item.

Request

bearer [ACCESS_TOKEN]
application/json

Request Body

objectin body

The item to assign the policy to

stringin bodyrequired
"6564564"

The ID of item to assign the policy to. Set to null or omit when type is set to enterprise.

stringin bodyrequired
"metadata_template"

The type of item to assign the policy to.

Value is one of enterprise,folder,metadata_template

object arrayin bodyoptional

If the assign_to type is metadata_template, then optionally add the filter_fields parameter which will require an array of objects with a field entry and a value entry. Currently only one object of field and value is supported.

stringin bodyoptional
"a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4"

The metadata attribute key id.

stringin bodyoptional
"0c27b756-0p87-4fe0-a43a-59fb661ccc4e"

The metadata attribute field id. For value, only enum and multiselect types are supported.

stringin bodyrequired
"173463"

The ID of the retention policy to assign

stringin bodyoptional
"upload_date"

The date the retention policy assignment begins.

If the assigned_to type is metadata_template, this field can be a date field's metadata attribute key id.

Response

Returns a new retention policy assignment object.

application/jsonClient error

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

Returns an error if start_date_field is present but assign_to.type is not metadata_template

Returns an error if start_date_field is present, but belongs to a different metadata template than the one specified in assign_to.id

Returns an error if start_date_field is present, but the retention_policy has a retention_length of "indefinite"

Returns an error if start_date_field is present, but cannot be resolved to a valid metadata date field.

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.

application/jsonClient error

An unexpected client error.

post
Assign 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 POST "https://api.box.com/2.0/retention_policy_assignments" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "policy_id": "173463",
       "assign_to": {
         "type": "folder",
         "id": "6564564"
       }
     }'
TypeScript Gen
await client.retentionPolicyAssignments.createRetentionPolicyAssignment({
  policyId: retentionPolicy.id,
  assignTo: {
    id: folder.id,
    type: 'folder' as CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField,
  } satisfies CreateRetentionPolicyAssignmentRequestBodyAssignToField,
} satisfies CreateRetentionPolicyAssignmentRequestBody);
Python Gen
client.retention_policy_assignments.create_retention_policy_assignment(
    retention_policy.id,
    CreateRetentionPolicyAssignmentAssignTo(
        id=folder.id, type=CreateRetentionPolicyAssignmentAssignToTypeField.FOLDER.value
    ),
)
.NET Gen
await client.RetentionPolicyAssignments.CreateRetentionPolicyAssignmentAsync(requestBody: new CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.Id, assignTo: new CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.Folder) { Id = folder.Id }));
Swift Gen (Beta)
try await client.retentionPolicyAssignments.createRetentionPolicyAssignment(requestBody: CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.id, assignTo: CreateRetentionPolicyAssignmentRequestBodyAssignToField(id: folder.id, type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.folder)))
Java
// Assign the policy to the entire enterprise
BoxRetentionPolicy policy = new BoxRetentionPolicy(api, policyID);
policy.assignToEnterprise();

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

// Assign the policy to all items with metadata template
String metadataTemplateID = "f0dce190-8106-43ca-9d67-7dce9b10a55e";
policy.assignToMetadataTemplate(metadataTemplateID);
// You can also pass an optional `startDateField` parameter containing the ID of the metadata template's `date` field
String dateFieldID = "fb523725-04b1-4502-b871-eac305274533";
policy.assignToMetadataTemplate(metadataTemplateID, dateFieldID);
Python
folder = client.folder(folder_id='1111')
assignment = client.retention_policy(retention_id='12345').assign(folder)
print(f'Assignment ID is {assignment.id} and it is assigned by {assignment.assigned_by.name}')
.NET
var assignmentParams = new BoxRetentionPolicyAssignmentRequest()
{
    PolicyId = "11111",
    AssignTo = new BoxRequestEntity()
    {
        Type = BoxType.folder,
        Id = "22222"
    }
};
BoxRetentionPolicyAssignment assignment = await client.RetentionPoliciesManager
    .CreateRetentionPolicyAssignmentAsync(assignmentParams);
Node
client.retentionPolicies
	.assign('11111', 'folder', '22222')
	.then((assignment) => {
		/* assignment -> {
			type: 'retention_policy_assignment',
			id: '12345',
			retention_policy:
			{ type: 'retention_policy',
				id: '11111',
				policy_name: 'Tax Documents' },
			assigned_to: { type: 'folder', id: '22222' },
			assigned_by:
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: 'user@example.com' },
			assigned_at: '2015-07-20T14:28:09-07:00' }
		*/
	});
iOS
client.retentionPolicy.assign(policyId: "12345",  assignedContentId: "1111", assignContentType: .folder) { result in
    guard case let .success(retentionPolicyAssignment) = result else {
        print("Error creating retention policy assignment")
        return
    }
    
    print("Retention policy assignment: \(retentionPolicyAssignment.id) was created")
}

Response Example

{
  "id": "11446498",
  "type": "retention_policy_assignment",
  "assigned_at": "2012-12-12T10:53:43-08:00",
  "assigned_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "assigned_to": {
    "id": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65",
    "type": "metadata_template"
  },
  "filter_fields": [
    {
      "field": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4",
      "value": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e"
    }
  ],
  "retention_policy": {
    "id": "12345",
    "type": "retention_policy",
    "disposition_action": "permanently_delete",
    "policy_name": "Some Policy Name",
    "retention_length": "365"
  },
  "start_date_field": "upload_date"
}