Create retention policy

post
https://api.box.com/2.0
/retention_policies/

Creates a retention policy.

Request

Bearer [ACCESS_TOKEN]
application/json

Request Body

booleanin bodyoptional
true

Whether owner and co-owners of a file are notified when the policy nears expiration.

booleanin bodyoptional
true

Whether the owner of a file will be allowed to extend the retention.

object arrayin bodyoptional
12312312

The id of the user to notify

user

Value is always user

apple@example.com

The email address the user uses to notify

Tim Apple

The name of the user to notify

stringin bodyrequired
permanently_delete

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.

Value is one of permanently_delete,remove_retention

stringin bodyrequired
Some Policy Name

The name for the retention policy

stringin bodyrequired
finite

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.

Value is one of finite,indefinite

string / int32in bodyoptional
3651

The length of the retention policy. This length 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.

Response

Returns a new retention policy object.

application/jsonClient error

Returns a bad_request error with the retention_length was specified for a infinite retention policy, or an incorrect disposition_action was set.

application/jsonClient error

Returns an error if a retention policy with the given name already exists

application/jsonClient error

An unexpected client error.

post
Create retention policy
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
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"
     }'
.NET
var policyParams = new BoxRetentionPolicyRequest()
{
    PolicyName = "Important Documents!",
    PolicyType = "finite",
    RetentionLength = 365,
    DispositionAction = "remove_retention"
};
BoxRetentionPolicy policy = await client.RetentionPoliciesManager
    .CreateRetentionPolicyAsync(policyParams);
Java
BoxRetentionPolicy.createIndefinitePolicy(api, name);
Python
policy_name = 'Test Indefinite Policy Name'
disposition_action = 'remove_retention'
indefinite_retention_policy = client.create_retention_policy(policy_name, disposition_action, float('inf'))
print('Indefinite Retention Policy ID is {0} and the policy name is {1}'.format(indefinite_retention_policy.id, indefinite_retention_policy.policy_name))
Node
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": "file_version",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": 11446498,
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "disposition_action": "permanently_delete",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "policy_name": "Some Policy Name",
  "policy_type": "finite",
  "retention_length": 365,
  "status": "active"
}