---
title: "Create legal hold policy"
method: POST
path: "/legal_hold_policies"
tags: ["Legal hold policies"]
---

# Create legal hold policy

`POST /legal_hold_policies`

Create a new legal hold policy.

## Request body

- object
  - `policy_name` string, required — The name of the policy.
  - `description` string — A description for the policy.
  - `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`.
  - `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`.
  - `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.

## Response `201`

Returns a new legal hold policy object.

- LegalHoldPolicy — A mini legal hold policy.
  - `id` string, required — The unique identifier for this legal hold policy.
  - `type` 'legal_hold_policy', required — The value will always be `legal_hold_policy`.
  - `policy_name` string — Name of the legal hold policy.
  - `description` string — Description of the legal hold policy. Optional property with a 500 character limit.
  - `status` 'active' | 'applying' | 'releasing' | 'released' — 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.
  - `assignment_counts` object — Counts of assignments within a legal hold policy by item type.
    - `user` integer — The number of users this policy is applied to with the `access` type assignment.
    - `folder` integer — The number of folders this policy is applied to.
    - `file` integer — The number of files this policy is applied to.
    - `file_version` integer — The number of file versions this policy is applied to.
    - `ownership` integer — The number of users this policy is applied to with the `ownership` type assignment.
    - `interactions` integer — The number of users this policy is applied to with the `interactions` type assignment.
  - `created_by` object — The user who created the legal hold policy object.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `created_at` string, date-time — When the legal hold policy object was created.
  - `modified_at` string, date-time — When the legal hold policy object was modified. Does not update when assignments are added or removed.
  - `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.
  - `filter_started_at` string, date-time — User-specified, optional date filter applies to Custodian assignments only.
  - `filter_ended_at` string, date-time — User-specified, optional date filter applies to Custodian assignments only.
  - `release_notes` string — Optional notes about why the policy was created.

## Other responses

- `400` — Returns an error if required parameters are missing, or neither `is_ongoing` or filter dates are specified.
- `409` — Returns an error if a policy with this name already exists.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)