Box Developer Documentation
Log in
Latest version

Assign legal hold policy

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

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

Assign a legal hold to a file, file version, folder, or user.

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

stringin bodyrequired
"folder"

The type of item to assign the policy to

Value is one of file,file_version,folder,user

stringin bodyrequired
"123244"

The ID of the policy to assign.

Response

application/jsonLegal hold policy assignment

Returns a new legal hold policy assignment.

application/jsonClient error

An unexpected client error.

post
Assign legal hold 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/legal_hold_policy_assignments" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "policy_id": "123244",
       "assign_to": {
         "type": "folder",
         "id": "6564564"
       }
     }'
TypeScript Gen
await client.legalHoldPolicyAssignments.createLegalHoldPolicyAssignment({
  policyId: legalHoldPolicyId,
  assignTo: {
    type: 'file' as CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField,
    id: fileId,
  } satisfies CreateLegalHoldPolicyAssignmentRequestBodyAssignToField,
} satisfies CreateLegalHoldPolicyAssignmentRequestBody);
Python Gen
client.legal_hold_policy_assignments.create_legal_hold_policy_assignment(
    legal_hold_policy_id,
    CreateLegalHoldPolicyAssignmentAssignTo(
        type=CreateLegalHoldPolicyAssignmentAssignToTypeField.FILE, id=file_id
    ),
)
.NET Gen
await client.LegalHoldPolicyAssignments.CreateLegalHoldPolicyAssignmentAsync(requestBody: new CreateLegalHoldPolicyAssignmentRequestBody(policyId: legalHoldPolicyId, assignTo: new CreateLegalHoldPolicyAssignmentRequestBodyAssignToField(type: CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField.File, id: fileId)));
Swift Gen (Beta)
try await client.legalHoldPolicyAssignments.createLegalHoldPolicyAssignment(requestBody: CreateLegalHoldPolicyAssignmentRequestBody(policyId: legalHoldPolicyId, assignTo: CreateLegalHoldPolicyAssignmentRequestBodyAssignToField(type: CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField.file, id: fileId)))
Java
BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, policyID);
BoxFolder folder = new BoxFolder(api, folderID);
policy.assignTo(folder);
Python
folder_to_assign = client.folder(folder_id='22222')
assignment = client.legal_hold_policy(policy_id'12345').assign(folder_to_assign)
print(f'Applied policy "{assignment.legal_hold_policy.policy_name}" to {assignment.assigned_to.type} {assignment.assigned_to.id}')
.NET
var requestParams = new BoxLegalHoldPolicyAssignmentRequest()
{
    PolicyId = "11111",
    AssignTo = new BoxRequestEntity()
    {
        Type = "folder",
        Id = "12345"
    }
};
BoxLegalHoldPolicyAssignment assignment = await client.LegalHoldPoliciesManager
    .CreateAssignmentAsync(requestParams);
Node
client.legalHoldPolicies.assign('11111', 'folder', '12345')
	.then(assignment => {
		/* assignment -> {
			type: 'legal_hold_policy_assignment',
			id: '22222',
			legal_hold_policy: 
			{ type: 'legal_hold_policy',
				id: '11111',
				policy_name: 'IRS Audit' },
			assigned_to: { type: 'folder', id: '12345' },
			assigned_by: 
			{ type: 'user',
				id: '33333',
				name: 'Example User',
				login: 'user@example.com' },
			assigned_at: '2016-05-18T17:38:03-07:00',
			deleted_at: null }
		*/
	});
iOS
client.legalHolds.forceApply(policyId: "1234", assignToId: "4568" ,assignToType: "file") { (result: Result<LegalHoldPolicyAssignment, BoxSDKError>) in
    guard case let .success(assignment) = result else {
        print("Error assigning legal hold policy")
        return
    }
    print("Assigned a legal hold policy at \"\(assignment.assignedAt)\"")
}

Response Example

{
  "id": "11446498",
  "type": "legal_hold_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": "12345",
    "type": "file",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "created_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "description": "Contract for Q1 renewal",
    "etag": "1",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "item_status": "active",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "name": "Contract.pdf",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "login": "ceo@example.com",
      "name": "Aaron Levie"
    },
    "parent": {
      "id": "12345",
      "type": "folder",
      "etag": "1",
      "name": "Contracts",
      "sequence_id": "3"
    },
    "path_collection": {
      "entries": [
        {
          "etag": "1",
          "id": "12345",
          "type": "folder",
          "name": "Contracts",
          "sequence_id": "3"
        }
      ],
      "total_count": 1
    },
    "purged_at": "2012-12-12T10:53:43-08:00",
    "sequence_id": "3",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "shared_link": {
      "access": "open",
      "download_count": 3,
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "effective_access": "company",
      "effective_permission": "can_download",
      "is_password_enabled": true,
      "permissions": {
        "can_download": true,
        "can_edit": false,
        "can_preview": true
      },
      "preview_count": 3,
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "vanity_name": "my_url",
      "vanity_url": "https://acme.app.box.com/v/my_url/"
    },
    "size": 629644,
    "trashed_at": "2012-12-12T10:53:43-08:00"
  },
  "deleted_at": "2012-12-12T10:53:43-08:00",
  "legal_hold_policy": {
    "id": "11446498",
    "type": "legal_hold_policy"
  }
}