Sample - Box Platform API
POST/retention_policies

Create a retention policy

Creates a new retention policy that controls how long content remains protected from deletion. Supply policy_name, policy_type, and disposition_action; finite policies use a duration in retention_length, while indefinite policies do not. The created policy can later be assigned to folders, metadata templates, or an enterprise.

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

10 body fields

Retention policy details. policy_name, policy_type, and disposition_action are required.

policy_namestringrequired
The name for the retention policy.
descriptionstringoptional
The additional text description of the retention policy.
policy_typestringrequired
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
disposition_actionstringrequired
The disposition action of the retention policy. `permanently_delete` deletes the content retained by the policy permanently. `remove_retention` lifts retention policy from the content, allowing it to be deleted by users once the retention policy has expired.
Allowed:permanently_deleteremove_retention
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`.
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
can_owner_extend_retentionbooleanoptional
Whether the owner of a file will be allowed to extend the 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. 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
Whether owner and co-owners of a file are notified when the policy nears expiration.
custom_notification_recipientsarray<UserMini>optional
A list of users notified when the retention policy duration is about to end.

4 status codes
201Returns the created 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.
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 retention_length is specified for an indefinite policy, disposition_action is invalid, max_extension_length is not allowed for the selected policy configuration, or description exceeds 500 characters. A 409 is returned when a retention policy with the same name already exists. policy_type must be finite or indefinite, and disposition_action must be permanently_delete or remove_retention.