Join BoxWorks 2024 to discover what's possible with content and AI!

Create retention policy

post

https://api.box.com/2.0

/retention_policies

Creates a retention policy.

Request

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

Request Body

are_owners_notified booleanin bodyoptional

exampletrue

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

Value is one of true,false

can_owner_extend_retention booleanin bodyoptional

exampletrue

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

Value is one of true,false

custom_notification_recipientsUser (Mini) arrayin bodyoptional

A list of users notified when the retention policy duration is about to end.

description stringin bodyoptional

example"Policy to retain all reports for at least one month"

The additional text description of the retention policy.

disposition_action stringin bodyrequired

example"permanently_delete"

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.

Value is one of permanently_delete,remove_retention

policy_name stringin bodyrequired

example"Some Policy Name"

The name for the retention policy

policy_type stringin bodyrequired

example"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

retention_length string (int32) / number (int32) in body

example"365"

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_type stringin bodyoptional

example"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.

Value is one of modifiable,non_modifiable

Response

201application/jsonRetention policy

Returns a new retention policy object.

400application/jsonClient error

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.

409application/jsonClient error

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

defaultapplication/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.

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"
     }'

TypeScript Gen

await client.retentionPolicies.createRetentionPolicy({
  policyName: getUuid(),
  policyType: 'finite' as CreateRetentionPolicyRequestBodyPolicyTypeField,
  dispositionAction:
    'remove_retention' as CreateRetentionPolicyRequestBodyDispositionActionField,
  retentionLength: '1',
  description: description,
  canOwnerExtendRetention: false,
  retentionType:
    'modifiable' as CreateRetentionPolicyRequestBodyRetentionTypeField,
} satisfies CreateRetentionPolicyRequestBody);

Python Gen

client.retention_policies.create_retention_policy(
    get_uuid(),
    CreateRetentionPolicyPolicyType.FINITE.value,
    CreateRetentionPolicyDispositionAction.REMOVE_RETENTION.value,
    description=description,
    retention_length="1",
    retention_type=CreateRetentionPolicyRetentionType.MODIFIABLE.value,
    can_owner_extend_retention=False,
)

.NET Gen

await client.RetentionPolicies.CreateRetentionPolicyAsync(requestBody: new CreateRetentionPolicyRequestBody(policyName: Utils.GetUUID(), policyType: CreateRetentionPolicyRequestBodyPolicyTypeField.Finite, dispositionAction: CreateRetentionPolicyRequestBodyDispositionActionField.RemoveRetention) { RetentionLength = "1", Description = description, CanOwnerExtendRetention = false, RetentionType = CreateRetentionPolicyRequestBodyRetentionTypeField.Modifiable });

Swift Gen (Beta)

try await client.retentionPolicies.createRetentionPolicy(requestBody: CreateRetentionPolicyRequestBody(policyName: Utils.getUUID(), policyType: CreateRetentionPolicyRequestBodyPolicyTypeField.finite, dispositionAction: CreateRetentionPolicyRequestBodyDispositionActionField.removeRetention, retentionLength: "1", description: description, canOwnerExtendRetention: false, retentionType: CreateRetentionPolicyRequestBodyRetentionTypeField.modifiable))

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(f'Indefinite Retention Policy ID is {indefinite_retention_policy.id} and the policy name is {indefinite_retention_policy.policy_name}')

.NET

var policyParams = new BoxRetentionPolicyRequest()
{
    PolicyName = "Important Documents!",
    PolicyType = "finite",
    RetentionLength = 365,
    DispositionAction = "remove_retention"
};
BoxRetentionPolicy policy = await client.RetentionPoliciesManager
    .CreateRetentionPolicyAsync(policyParams);

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',
		retention_type: 'modifiable',
		description: 'Policy to retain all reports',
		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' }
	*/
});

iOS

client.retentionPolicy.create(
    name: "Test Indefinite Policy Name",
    type: .indefinite,
    dispositionAction: .removeRetention
) { result in
    guard case let .success(retentionPolicy) = result else {
        print("Error creating retention policy")
        return
    }
    
    print("Retention policy: \(retentionPolicy.id) was created")
}

Response Example

{
  "id": "12345",
  "type": "retention_policy",
  "are_owners_notified": false,
  "assignment_counts": {
    "enterprise": 1,
    "folder": 1,
    "metadata_template": 1
  },
  "can_owner_extend_retention": false,
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    }
  ],
  "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"
}