Create retention policy
Creates a retention policy.
Request
Request Body
trueWhether owner and co-owners of a file are notified when the policy nears expiration.
trueWhether the owner of a file will be allowed to extend the retention.
12312312The id of the user to notify
userValue is always user
apple@example.comThe email address the user uses to notify
Tim AppleThe name of the user to notify
Policy to retain all reports for at least one monthThe additional text description of the retention policy.
permanently_deleteThe 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.
Value is one of permanently_delete,remove_retention
Some Policy NameThe name for the retention policy
finiteThe 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.
Value is one of finite,indefinite
3651The 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.
modifiableSpecifies 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.
Value is one of modifiable,non-modifiable
Response
Returns a new retention policy object.
Returns a bad_request error with the retention_length was
specified for a infinite retention policy, an incorrect
disposition_action was set, or description exceeds maximum length of
500 characters.
Returns an error if a retention policy with the given name already exists
An unexpected client error.
Request Example
curl -i -X POST "https://api.box.com/2.0/retention_policies" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"policy_name": "Some Policy Name",
"policy_type": "finite",
"retention_length": 365,
"disposition_action": "permanently_delete"
}'var policyParams = new BoxRetentionPolicyRequest()
{
PolicyName = "Important Documents!",
PolicyType = "finite",
RetentionLength = 365,
DispositionAction = "remove_retention"
};
BoxRetentionPolicy policy = await client.RetentionPoliciesManager
.CreateRetentionPolicyAsync(policyParams);BoxRetentionPolicy.createIndefinitePolicy(api, name);policy_name = 'Test Indefinite Policy Name'
disposition_action = 'remove_retention'
indefinite_retention_policy = client.create_retention_policy(policy_name, disposition_action, float('inf'))
print(f'Indefinite Retention Policy ID is {indefinite_retention_policy.id} and the policy name is {indefinite_retention_policy.policy_name}')client.retentionPolicies.create(
'Tax Documents',
client.retentionPolicies.policyTypes.INDEFINITE,
client.retentionPolicies.dispositionActions.REMOVE_RETENTION)
).then(policy => {
/* policy -> {
type: 'retention_policy',
id: '123456789',
policy_name: 'Tax Documents',
policy_type: 'indefinite',
retention_length: 'indefinite',
disposition_action: 'remove_retention',
can_owner_extend_retention: false,
status: 'active',
are_owners_notified: true,
custom_notification_recipients: []
assignment_counts: { enterprise: 0, folder: 1, metadata_template: 0 },
created_by:
{ type: 'user',
id: '11111',
name: 'Example User',
login: 'user@example.com' },
created_at: '2015-05-01T11:12:54-07:00',
modified_at: '2015-06-08T11:11:50-07:00' }
*/
});Response Example
{
"id": 12345,
"type": "retention_policy",
"created_at": "2012-12-12T10:53:43-08:00",
"created_by": {
"id": 11446498,
"type": "user",
"login": "ceo@example.com",
"name": "Aaron Levie"
},
"description": "Policy to retain all reports for at least one month",
"disposition_action": "permanently_delete",
"modified_at": "2012-12-12T10:53:43-08:00",
"policy_name": "Some Policy Name",
"policy_type": "finite",
"retention_length": 365,
"retention_type": "non-modifiable",
"status": "active"
}