Manage Applications

    Create retention policy

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

    Creates a retention policy.

    Request

    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.

    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 time period has passed.

    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
    0

    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

    application/jsonRetention Policy

    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

    You can now try out some of our APIs live, right here in the documentation.
    Log In

    Request Example

    cURL
    curl -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": 11446498,
      "type": "retention_policy",
      "policy_name": "Some Policy Name",
      "policy_type": "finite",
      "retention_length": 0,
      "disposition_action": "permanently_delete",
      "status": "active",
      "created_by": {
        "id": 11446498,
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00"
    }