Skip to main content
POST
/
retention_policy_assignments
cURL
curl -i -X POST "https://api.box.com/2.0/retention_policy_assignments" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "policy_id": "173463",
       "assign_to": {
         "type": "folder",
         "id": "6564564"
       }
     }'
{
  "id": "11446498",
  "type": "retention_policy_assignment",
  "retention_policy": {
    "id": "12345",
    "type": "retention_policy",
    "policy_name": "Some Policy Name",
    "retention_length": "365",
    "disposition_action": "permanently_delete"
  },
  "assigned_to": {
    "id": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65",
    "type": "metadata_template"
  },
  "filter_fields": [
    {
      "field": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4",
      "value": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e"
    }
  ],
  "assigned_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "assigned_at": "2012-12-12T10:53:43-08:00",
  "start_date_field": "upload_date"
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
policy_id
string
required

The ID of the retention policy to assign.

Example:

"173463"

​
assign_to
object
required

The item to assign the policy to.

​
filter_fields
object[]

If the assign_to type is metadata_template, then optionally add the filter_fields parameter which will require an array of objects with a field entry and a value entry. Currently only one object of field and value is supported.

​
start_date_field
string

The date the retention policy assignment begins.

If the assigned_to type is metadata_template, this field can be a date field's metadata attribute key id.

Example:

"upload_date"

Response

Returns a new retention policy assignment object.

A retention assignment represents a rule specifying the files a retention policy retains. Assignments can retain files based on their folder or metadata, or hold all files in the enterprise.

​
id
string
required

The unique identifier for a retention policy assignment.

Example:

"11446498"

​
type
enum<string>
required

The value will always be retention_policy_assignment.

Available options:
retention_policy_assignment
Example:

"retention_policy_assignment"

​
retention_policy
Retention policy (Mini) · object

A mini representation of a retention policy object that has been assigned to the content.

​
assigned_to
object

The type and id of the content that is under retention. The type can either be folder enterprise, or metadata_template.

​
filter_fields
(object | null)[] | null

An array of field objects. Values are only returned if the assigned_to type is metadata_template. Otherwise, the array is blank.

​
assigned_by
User (Mini) · object

A mini user object representing the user that created the retention policy assignment.

​
assigned_at
string<date-time>

When the retention policy assignment object was created.

Example:

"2012-12-12T10:53:43-08:00"

​
start_date_field
string

The date the retention policy assignment begins. If the assigned_to type is metadata_template, this field can be a date field's metadata attribute key id.

Example:

"upload_date"