Manage Applications

    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": 11446498,
        "type": "retention_policy",
        "policy_name": "Some Policy Name"
      "assigned_to": {
        "id": 11446498
      "assigned_by": {
        "id": 11446498,
        "type": "user",
        "name": "Aaron Levie",
        "login": ""
      "assigned_at": "2012-12-12T10:53:43-08:00"