--- title: "Update retention policy" method: PUT path: "/retention_policies/{retention_policy_id}" tags: ["Retention policies"] --- # Update retention policy `PUT /retention_policies/{retention_policy_id}` Updates a retention policy. ## Path parameters - `retention_policy_id` string, required ## Request body - object - `policy_name` string, nullable — The name for the retention policy. - `description` string, nullable — The additional text description of the retention policy. - `disposition_action` union — The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. You can use `null` if you don't want to change `disposition_action`. - 'permanently_delete' | 'remove_retention' - string, nullable - `retention_type` string, nullable — Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. When updating a retention policy, you can use `non-modifiable` type only. You can convert a `modifiable` policy to `non-modifiable`, but not the other way around. - `retention_length` union — The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. - string, int32, nullable - number - `status` string, nullable — Used to retire a retention policy. If not retiring a policy, do not include this parameter or set it to `null`. - `can_owner_extend_retention` boolean, nullable — Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. - `max_extension_length` union — The maximum extension length of the retention date. This value specifies the duration in days for which the retention date of the file under policy can be extended. It can be specified only for the 'finite' policy type where the disposition action is 'permanently delete', otherwise the server will return status 400. If this value is 'none', it won't be possible to extend the retention. - 'none' - string, int32 - integer - `are_owners_notified` boolean, nullable — Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. - `custom_notification_recipients` UserBase[], nullable — A list of users notified when the retention duration is about to end. - `id` string, required — The unique identifier for this user. - `type` 'user', required — The value will always be `user`. ## Response `200` Returns the updated retention policy object. - RetentionPolicy — A base representation of a retention policy. - `id` string, required — The unique identifier that represents a retention policy. - `type` 'retention_policy', required — The value will always be `retention_policy`. - `policy_name` string — The name given to the retention policy. - `retention_length` string, int32 — The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. - `disposition_action` 'permanently_delete' | 'remove_retention' — The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. - `max_extension_length` union — The maximum extension length of the retention date. This value specifies the duration in days for which the retention date of the file under policy can be extended. If the policy type is other than 'finite' or the disposition action is other than 'permanently delete', or the maximum extension length is undefined, this field will be set to 'none'. - 'none' - string, int32 - `description` string — The additional text description of the retention policy. - `policy_type` 'finite' | 'indefinite' — The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown. - `retention_type` 'modifiable' | 'non_modifiable' — Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. - `status` 'active' | 'retired' — The status of the retention policy. The status of a policy will be `active`, unless explicitly retired by an administrator, in which case the status will be `retired`. Once a policy has been retired, it cannot become active again. - `created_by` object — A mini user object representing the user that created the retention policy. - `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 retention policy object was created. - `modified_at` string, date-time — When the retention policy object was last modified. - `can_owner_extend_retention` boolean — Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. - `are_owners_notified` boolean — Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. - `custom_notification_recipients` UserMini[] — A list of users notified when the retention policy duration is about to end. - `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. - `assignment_counts` object — Counts the retention policy assignments for each item type. - `enterprise` integer — The number of enterprise assignments this policy has. The maximum value is 1. - `folder` integer — The number of folder assignments this policy has. - `metadata_template` integer — The number of metadata template assignments this policy has. ## Other responses - `400` — Returns a `bad_request` if an incorrect `disposition_action` was set, `max_extension_length` is not allowed for the given policy type or disposition action, or description exceeds maximum length of 500 characters. - `403` — Returns an error when a user wants to shorten the duration of a non-modifiable policy, or to convert a non-modifiable policy to a modifiable one. Note: Lengthening policy duration is allowed. - `409` — Returns an error if a retention policy with the given 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)