Box Developer Documentation
Log in
Latest version

Create legal hold policy

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

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

Create a new legal hold policy.

Request

bearer [ACCESS_TOKEN]
application/json

Request Body

stringin bodyoptional
"A custom policy for the sales team"
500

A description for the policy.

string (date-time)in bodyoptional
"2012-12-18T10:53:43-08:00"
500

The filter end date.

When this policy is applied using a custodian legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter.

Required if is_ongoing is set to false.

string (date-time)in bodyoptional
"2012-12-12T10:53:43-08:00"
500

The filter start date.

When this policy is applied using a custodian legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter.

Required if is_ongoing is set to false.

booleanin bodyoptional
true

Whether new assignments under this policy should continue applying to files even after initialization.

When this policy is applied using a legal hold assignment, it will continue applying the policy to any new file versions even after it has been applied.

For example, if a legal hold assignment is placed on a user today, and that user uploads a file tomorrow, that file will get held. This will continue until the policy is retired.

Required if no filter dates are set.

stringin bodyrequired
"Sales Policy"
254

The name of the policy.

Response

application/jsonLegal hold policy

Returns a new legal hold policy object.

application/jsonClient error

Returns an error if required parameters are missing, or neither is_ongoing or filter dates are specified.

application/jsonClient error

Returns an error if a policy with this name already exists.

application/jsonClient error

An unexpected client error.

post
Create legal hold policy
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

Learn more about Box SDK versioning strategy.


cURL
curl -i -X POST "https://api.box.com/2.0/legal_hold_policies" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "policy_name": "Policy 3",
       "description": "Automatic created policy"
     }'
Node/TypeScript v10
await client.legalHoldPolicies.createLegalHoldPolicy({
  policyName: legalHoldPolicyName,
  description: legalHoldDescription,
  isOngoing: false,
  filterStartedAt: filterStartedAt,
  filterEndedAt: filterEndedAt,
} satisfies CreateLegalHoldPolicyRequestBody);
Python v10
client.legal_hold_policies.create_legal_hold_policy(
    legal_hold_policy_name,
    description=legal_hold_description,
    filter_started_at=filter_started_at,
    filter_ended_at=filter_ended_at,
    is_ongoing=False,
)
.NET v10
await client.LegalHoldPolicies.CreateLegalHoldPolicyAsync(requestBody: new CreateLegalHoldPolicyRequestBody(policyName: legalHoldPolicyName) { Description = legalHoldDescription, IsOngoing = false, FilterStartedAt = filterStartedAt, FilterEndedAt = filterEndedAt });
Swift v10
try await client.legalHoldPolicies.createLegalHoldPolicy(requestBody: CreateLegalHoldPolicyRequestBody(policyName: legalHoldPolicyName, description: legalHoldDescription, isOngoing: false, filterStartedAt: filterStartedAt, filterEndedAt: filterEndedAt))
Java v10
client.getLegalHoldPolicies().createLegalHoldPolicy(new CreateLegalHoldPolicyRequestBody.Builder(legalHoldPolicyName).description(legalHoldDescription).filterStartedAt(filterStartedAt).filterEndedAt(filterEndedAt).isOngoing(false).build())
Java v5
BoxLegalHoldPolicy.Info policyInfo = BoxLegalHoldPolicy.create(api, name, description, startedAt, endedAt);
Python v4
new_policy = client.create_legal_hold_policy('New Policy', is_ongoing=True)
print(f'Created legal hold policy with ID {new_policy.id}')
.NET v6
var policyParams = new BoxLegalHoldPolicyRequest()
{
    PolicyName = "IRS Audit"
};
BoxLegalHoldPolicy policy = await client.LegalHoldPoliciesManager
    .CreateLegalHoldPolicyAsync(policyParams);
Node v4
client.legalHoldPolicies.create('IRS Audit')
	.then(policy => {
		/* policy -> {
			type: 'legal_hold_policy',
			id: '11111',
			policy_name: 'IRS Audit',
			description: '',
			status: 'active',
			assignment_counts: { user: 0, folder: 0, file: 0, file_version: 0 },
			is_ongoing: true,
			created_by: 
			{ type: 'user',
				id: '22222',
				name: 'Example User',
				login: 'user@example.com' },
			created_at: '2017-01-24T16:57:22-08:00',
			modified_at: '2017-01-24T16:57:22-08:00',
			deleted_at: null,
			filter_started_at: null,
			filter_ended_at: null }
		*/
	});

Response Example

{
  "id": "11446498",
  "type": "legal_hold_policy",
  "assignment_counts": {
    "file": 3,
    "file_version": 4,
    "folder": 2,
    "user": 1
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "deleted_at": "2012-12-12T10:53:43-08:00",
  "description": "Postman created policy",
  "filter_ended_at": "2012-12-12T10:53:43-08:00",
  "filter_started_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "policy_name": "Policy 4",
  "release_notes": "Example",
  "status": "active"
}