Sample - Box Platform API
POST/legal_hold_policies

Create a legal hold policy

Creates a new legal hold policy. Supply policy_name and, when the policy is not ongoing, provide the applicable filter dates; use filter_started_at and filter_ended_at in ISO 8601 date-time format. A 201 response returns the created legal hold policy object.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

5 body fields

Legal hold policy details used to create a policy.

policy_namestringrequired
The name of the policy.
descriptionstringoptional
A description for the policy.
filter_started_atstringoptional
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`.
filter_ended_atstringoptional
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`.
is_ongoingbooleanoptional
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.

4 status codes
201Returns the created legal hold policy object, including its identifier, name, status, assignment counts, and filter dates.
idstringrequired
The unique identifier for this legal hold policy.
typestringrequired
The value will always be `legal_hold_policy`.
Allowed:legal_hold_policy
policy_namestringoptional
Name of the legal hold policy.
descriptionstringoptional
Description of the legal hold policy. Optional property with a 500 character limit.
statusstringoptional
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.
Allowed:activeapplyingreleasingreleased
assignment_countsobjectoptional
Counts of assignments within a legal hold policy by item type.
created_byobjectoptional
created_atstringoptional
When the legal hold policy object was created.
modified_atstringoptional
When the legal hold policy object was modified. Does not update when assignments are added or removed.
deleted_atstringoptional
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.
filter_started_atstringoptional
User-specified, optional date filter applies to Custodian assignments only.
filter_ended_atstringoptional
User-specified, optional date filter applies to Custodian assignments only.
release_notesstringoptional
Optional notes about why the policy was created.
400Returned when required parameters are missing or neither `is_ongoing` nor filter dates are specified.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
409Returned when a legal hold policy with the specified name already exists.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

policy_name is required, and a request must specify either is_ongoing or the applicable filter dates; a request that fails these requirements returns a 400. policy_name must not exceed 254 characters, while description must not exceed 500 characters. A 409 is returned when a policy with the same name already exists.