---
title: "Assign retention policy"
method: POST
path: "/retention_policy_assignments"
tags: ["Retention policy assignments"]
---

# Assign retention policy

`POST /retention_policy_assignments`

Assigns a retention policy to an item.

## Request body

- object
  - `policy_id` string, required — The ID of the retention policy to assign.
  - `assign_to` object, required — The item to assign the policy to.
    - `type` 'enterprise' | 'folder' | 'metadata_template', required — The type of item to assign the policy to.
    - `id` string, nullable — The ID of item to assign the policy to. Set to `null` or omit when `type` is set to `enterprise`.
  - `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.
    - `field` string — The metadata attribute key id.
    - `value` string — The metadata attribute field id. For value, only enum and multiselect types are 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.

## Response `201`

Returns a new retention policy assignment object.

- RetentionPolicyAssignment — 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.
  - `type` 'retention_policy_assignment', required — The value will always be `retention_policy_assignment`.
  - `retention_policy` object — A mini representation of a retention policy object that has been assigned to the content.
    - `id` string, required — The unique identifier that represents a retention policy.
    - `type` 'retention_policy', required — The value will always be `retention_policy`.
    - `policy_name` string — The name given to the retention policy.
    - `retention_length` string, int32 — 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`.
    - `disposition_action` 'permanently_delete' | 'remove_retention' — 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.
    - `max_extension_length` union — The maximum extension length of the retention date. This value specifies the duration in days for which the retention date of the file under policy can be extended. If the policy type is other than 'finite' or the disposition action is other than 'permanently delete', or the maximum extension length is undefined, this field will be set to 'none'.
      - 'none'
      - string, int32
  - `assigned_to` object — The `type` and `id` of the content that is under retention. The `type` can either be `folder` `enterprise`, or `metadata_template`.
    - `id` string, nullable — The ID of the folder, enterprise, or metadata template the policy is assigned to. Set to null or omit when type is set to enterprise.
    - `type` 'folder' | 'enterprise' | 'metadata_template' — The type of resource the policy is assigned to.
  - `filter_fields` object[], nullable — An array of field objects. Values are only returned if the `assigned_to` type is `metadata_template`. Otherwise, the array is blank.
    - `field` string, nullable — The metadata attribute key id.
    - `value` string, nullable — The metadata attribute field id. For value, only enum and multiselect types are supported.
  - `assigned_by` object — A mini user object representing the user that created the retention policy assignment.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `assigned_at` string, date-time — When the retention policy assignment object was created.
  - `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.

## Other responses

- `400` — Returns an error if an `id` is specified while assigning the retention policy to an enterprise. Returns an error if `start_date_field` is present but `assign_to.type` is not `metadata_template` Returns an error if `start_date_field` is present, but belongs to a different metadata template than the one specified in `assign_to.id` Returns an error if `start_date_field` is present, but the `retention_policy` has a `retention_length` of "indefinite" Returns an error if `start_date_field` is present, but cannot be resolved to a valid metadata date field.
- `404` — Returns an error if no retention policy with the given `policy_id` exists.
- `409` — Returns an error if a retention policy of equal or greater length has already been assigned to this item.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)