Skip to main content
POST
/
legal_hold_policies
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"
     }'
{
  "id": "11446498",
  "type": "legal_hold_policy",
  "policy_name": "Policy 4",
  "description": "Postman created policy",
  "status": "active",
  "assignment_counts": {
    "user": 1,
    "folder": 2,
    "file": 3,
    "file_version": 4
  },
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "deleted_at": "2012-12-12T10:53:43-08:00",
  "filter_started_at": "2012-12-12T10:53:43-08:00",
  "filter_ended_at": "2012-12-12T10:53:43-08:00",
  "release_notes": "Example"
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
policy_name
string
required

The name of the policy.

Maximum string length: 254
Example:

"Sales Policy"

​
description
string

A description for the policy.

Maximum string length: 500
Example:

"A custom policy for the sales team"

​
filter_started_at
string<date-time>

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.

Maximum string length: 500
Example:

"2012-12-12T10:53:43-08:00"

​
filter_ended_at
string<date-time>

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.

Maximum string length: 500
Example:

"2012-12-18T10:53:43-08:00"

​
is_ongoing
boolean

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.

Example:

true

Response

Returns a new legal hold policy object.

Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates.

​
id
string
required

The unique identifier for this legal hold policy.

Example:

"11446498"

​
type
enum<string>
required

The value will always be legal_hold_policy.

Available options:
legal_hold_policy
Example:

"legal_hold_policy"

​
policy_name
string

Name of the legal hold policy.

Maximum string length: 254
Example:

"Policy 4"

​
description
string

Description of the legal hold policy. Optional property with a 500 character limit.

Maximum string length: 500
Example:

"Postman created policy"

​
status
enum<string>

Possible values:

  • 'active' - the policy is not in a transition state.
  • 'applying' - that the policy is in the process of being applied.
  • 'releasing' - that the process is in the process of being released.
  • 'released' - the policy is no longer active.
Available options:
active,
applying,
releasing,
released
Example:

"active"

​
assignment_counts
object

Counts of assignments within this a legal hold policy by item type.

​
created_by
User (Mini) · object

The user who created the legal hold policy object.

​
created_at
string<date-time>

When the legal hold policy object was created.

Example:

"2012-12-12T10:53:43-08:00"

​
modified_at
string<date-time>

When the legal hold policy object was modified. Does not update when assignments are added or removed.

Example:

"2012-12-12T10:53:43-08:00"

​
deleted_at
string<date-time>

When the policy release request was sent. (Because it can take time for a policy to fully delete, this isn't quite the same time that the policy is fully deleted).

If null, the policy was not deleted.

Example:

"2012-12-12T10:53:43-08:00"

​
filter_started_at
string<date-time>

User-specified, optional date filter applies to Custodian assignments only.

Example:

"2012-12-12T10:53:43-08:00"

​
filter_ended_at
string<date-time>

User-specified, optional date filter applies to Custodian assignments only.

Example:

"2012-12-12T10:53:43-08:00"

​
release_notes
string

Optional notes about why the policy was created.

Maximum string length: 500
Example:

"Example"