Sample - Box Platform API
PUT/retention_policies/{retention_policy_id}

Update a retention policy

Updates an existing retention policy and returns its current configuration. Supply only the policy attributes you want to change, including retention_length, notification settings, or the disposition action. Set status when you want to retire the policy.

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

1 parameter · 10 body fields
retention_policy_idstringrequired
The unique identifier of the retention policy to update.

Retention policy attributes to update.

policy_namestringoptional
The name for the retention policy.
descriptionstringoptional
The additional text description of the retention policy.
disposition_actionstringoptional
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`.
Allowed:permanently_deleteremove_retention
retention_typestringoptional
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_lengthstringoptional
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`.
statusstringoptional
Used to retire a retention policy. If not retiring a policy, do not include this parameter or set it to `null`.
can_owner_extend_retentionbooleanoptional
Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end.
max_extension_lengthstringoptional
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.
Allowed:none
are_owners_notifiedbooleanoptional
Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end.
custom_notification_recipientsarray<UserBase>optional
A list of users notified when the retention duration is about to end.

5 status codes
200Returns the updated retention policy object.
idstringrequired
The unique identifier that represents a retention policy.
typestringrequired
The value will always be `retention_policy`.
Allowed:retention_policy
policy_namestringoptional
The name given to the retention policy.
retention_lengthstringoptional
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_actionstringoptional
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.
Allowed:permanently_deleteremove_retention
max_extension_lengthstringoptional
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'.
Allowed:none
descriptionstringoptional
The additional text description of the retention policy.
policy_typestringoptional
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.
Allowed:finiteindefinite
retention_typestringoptional
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.
Allowed:modifiablenon_modifiable
statusstringoptional
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.
Allowed:activeretired
created_byobjectoptional
created_atstringoptional
When the retention policy object was created.
modified_atstringoptional
When the retention policy object was last modified.
can_owner_extend_retentionbooleanoptional
Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end.
are_owners_notifiedbooleanoptional
Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end.
custom_notification_recipientsarray<UserMini>optional
A list of users notified when the retention policy duration is about to end.
assignment_countsobjectoptional
Counts the retention policy assignments for each item type.
400Returned when the retention configuration is invalid or `description` exceeds 500 characters.
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.
403Returned when you try to shorten a non-modifiable policy or convert it to a modifiable policy.
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 retention policy with the given 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.
defaultReturns an 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

A 400 is returned when disposition_action is invalid, max_extension_length is not allowed for the selected policy configuration, or description exceeds 500 characters. A 403 is returned when you try to shorten a non-modifiable policy or convert it to a modifiable policy. A 409 is returned when a retention policy with the same name already exists.