Sample - Box Platform API
POST/retention_policy_assignments

Assign a retention policy

Creates an assignment that applies a retention policy to an enterprise, folder, or metadata template. Supply policy_id and an assign_to object with the target type, and include filter_fields or start_date_field only when assigning to a metadata template. The resulting assignment identifies the retained content and the policy applied to it.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

4 body fields

Retention policy assignment details. policy_id and assign_to are required.

policy_idstringrequired
The ID of the retention policy to assign.
assign_toobjectrequired
The item to assign the policy to.
filter_fieldsarray<object>optional
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_fieldstringoptional
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.

5 status codes
201Returns the created retention policy assignment object.
idstringrequired
The unique identifier for a retention policy assignment.
typestringrequired
The value will always be `retention_policy_assignment`.
Allowed:retention_policy_assignment
retention_policyobjectoptional
assigned_toobjectoptional
The `type` and `id` of the content that is under retention. The `type` can either be `folder` `enterprise`, or `metadata_template`.
filter_fieldsarray<object>optional
An array of field objects. Values are only returned if the `assigned_to` type is `metadata_template`. Otherwise, the array is blank.
assigned_byobjectoptional
assigned_atstringoptional
When the retention policy assignment object was created.
start_date_fieldstringoptional
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.
400Returned when the assignment target or `start_date_field` configuration is invalid.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when no retention policy exists with the specified `policy_id`.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
409Returned when an equal or longer retention policy is already assigned to the target.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultReturns an unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when an enterprise assignment includes an id, when start_date_field is used with a non-metadata-template target, or when the field cannot be resolved or is incompatible with the policy. A 404 is returned when policy_id does not identify an existing retention policy. A 409 is returned when an equal or longer retention policy is already assigned to the target.