Box Legal Hold Policies API
The Box Legal Hold Policies API enables creating and managing legal hold policies that prevent content from being modified or deleted during legal proceedings, supporting e-discovery and litigation hold requirements.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Legal Hold Policies API
description: Needs a description.
paths:
/legal_hold_policies:
get:
operationId: get_legal_hold_policies
summary: Box List all legal hold policies
tags:
- Legal Hold Policies
x-box-tag: legal_hold_policies
description: |-
Retrieves a list of legal hold policies that belong to
an enterprise.
parameters:
- name: policy_name
description: |-
Limits results to policies for which the names start with
this search term. This is a case-insensitive prefix.
in: query
example: Sales Policy
required: false
schema:
type: string
- name: fields
description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
responses:
'200':
description: Returns a list of legal hold policies.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHoldPolicies'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_legal_hold_policies
summary: Box Create legal hold policy
tags:
- Legal Hold Policies
x-box-tag: legal_hold_policies
description: Create a new legal hold policy.
requestBody:
content:
application/json:
schema:
type: object
required:
- policy_name
properties:
policy_name:
description: The name of the policy.
example: Sales Policy
type: string
maxLength: 254
description:
description: A description for the policy.
example: A custom policy for the sales team
type: string
maxLength: 500
filter_started_at:
description: |-
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`.
example: '2012-12-12T10:53:43-08:00'
type: string
maxLength: 500
format: date-time
filter_ended_at:
description: |-
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`.
example: '2012-12-18T10:53:43-08:00'
type: string
maxLength: 500
format: date-time
is_ongoing:
description: >-
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
type: boolean
responses:
'201':
description: Returns a new legal hold policy object.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHoldPolicy'
'400':
description: |-
Returns an error if required parameters are missing,
or neither `is_ongoing` or filter dates are specified.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: Returns an error if a policy with this name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/legal_hold_policies/{legal_hold_policy_id}:
get:
operationId: get_legal_hold_policies_id
summary: Box Get legal hold policy
tags:
- Legal Hold Policies
x-box-tag: legal_hold_policies
description: Retrieve a legal hold policy.
parameters:
- name: legal_hold_policy_id
description: The ID of the legal hold policy
example: '324432'
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns a legal hold policy object.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHoldPolicy'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_legal_hold_policies_id
summary: Box Update legal hold policy
tags:
- Legal Hold Policies
x-box-tag: legal_hold_policies
description: Update legal hold policy.
parameters:
- name: legal_hold_policy_id
description: The ID of the legal hold policy
example: '324432'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
policy_name:
description: The name of the policy.
example: Sales Policy
type: string
maxLength: 254
description:
description: A description for the policy.
example: A custom policy for the sales team
type: string
maxLength: 500
release_notes:
description: Notes around why the policy was released.
example: Required for GDPR
type: string
maxLength: 500
responses:
'200':
description: Returns a new legal hold policy object.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHoldPolicy'
'409':
description: Returns an error if a policy with this name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_legal_hold_policies_id
x-box-tag: legal_hold_policies
tags:
- Legal Hold Policies
summary: Box Remove legal hold policy
description: |-
Delete an existing legal hold policy.
This is an asynchronous process. The policy will not be
fully deleted yet when the response returns.
parameters:
- name: legal_hold_policy_id
description: The ID of the legal hold policy
example: '324432'
in: path
required: true
schema:
type: string
responses:
'202':
description: |-
A blank response is returned if the policy was
successfully deleted.
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
LegalHoldPolicies:
title: Legal hold policies
type: object
x-box-resource-id: legal_hold_policies
x-box-tag: legal_hold_policies
description: A list of legal hold policies.
allOf:
- type: object
description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
nullable: true
prev_marker:
description: The marker for the start of the previous page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
type: string
nullable: true
- properties:
entries:
type: array
description: A list of legal hold policies
items:
$ref: '#/components/schemas/LegalHoldPolicy'
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
message:
description: A short message describing the error.
example: Method Not Allowed
type: string
nullable: false
context_info:
description: |-
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.
type: object
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
help_url:
description: A URL that links to more information about why this error occurred.
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
type: string
nullable: false
request_id:
description: |-
A unique identifier for this response, which can be used
when contacting Box support.
type: string
example: abcdef123456
nullable: false
LegalHoldPolicy:
title: Legal hold policy
type: object
x-box-resource-id: legal_hold_policy
x-box-variant: standard
description: |-
Legal Hold Policy information describes the basic
characteristics of the Policy, such as name, description,
and filter dates.
allOf:
- $ref: '#/components/schemas/LegalHoldPolicy--Mini'
- properties:
policy_name:
type: string
example: Policy 4
description: Name of the legal hold policy.
maxLength: 254
description:
type: string
description: |-
Description of the legal hold policy. Optional
property with a 500 character limit.
maxLength: 500
example: Postman created policy
status:
type: string
example: active
enum:
- active
- applying
- releasing
- released
description: |-
* '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
assignment_counts:
type: object
description: >-
Counts of assignments within this a legal hold policy by item
type
properties:
user:
type: integer
format: int64
description: The number of users this policy is applied to
example: 1
folder:
type: integer
format: int64
description: The number of folders this policy is applied to
example: 2
file:
type: integer
format: int64
description: The number of files this policy is applied to
example: 3
file_version:
type: integer
format: int64
description: The number of file versions this policy is applied to
example: 4
created_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who created the legal hold policy object
created_at:
type: string
format: date-time
description: When the legal hold policy object was created
example: '2012-12-12T10:53:43-08:00'
modified_at:
type: string
format: date-time
description: |-
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:
type: string
format: date-time
description: |-
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:
type: string
format: date-time
description: |-
User-specified, optional date filter applies to
Custodian assignments only
example: '2012-12-12T10:53:43-08:00'
filter_ended_at:
type: string
format: date-time
description: |-
User-specified, optional date filter applies to
Custodian assignments only
example: '2012-12-12T10:53:43-08:00'
release_notes:
type: string
example: Example
description: Optional notes about why the policy was created.
maxLength: 500
tags:
- name: Legal Hold Policies