Sample - Box Platform API
GET/retention_policies/{retention_policy_id}

Get a retention policy

Retrieves a retention policy by its identifier. Use fields to request additional attributes that are not included in the standard response. When you specify fields, the response contains the mini representation together with the requested attributes instead of the standard fields.

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

2 parameters
retention_policy_idstringrequired
The unique identifier of the retention policy to retrieve.
fieldsarray<string>optional
A comma-separated list of retention policy attributes to include in the response. Specifying this parameter limits the response to the mini representation and the requested fields.

2 status codes
200Returns the requested retention policy object.
idstringrequired
The unique identifier that represents a retention policy.
typestringrequired
The value will always be `retention_policy`.
Allowed:retention_policy
policy_namestringoptional
The name given to the retention policy.
retention_lengthstringoptional
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_actionstringoptional
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.
Allowed:permanently_deleteremove_retention
max_extension_lengthstringoptional
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'.
Allowed:none
descriptionstringoptional
The additional text description of the retention policy.
policy_typestringoptional
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.
Allowed:finiteindefinite
retention_typestringoptional
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.
Allowed:modifiablenon_modifiable
statusstringoptional
The status of the retention policy. The status of a policy will be `active`, unless explicitly retired by an administrator, in which case the status will be `retired`. Once a policy has been retired, it cannot become active again.
Allowed:activeretired
created_byobjectoptional
created_atstringoptional
When the retention policy object was created.
modified_atstringoptional
When the retention policy object was last modified.
can_owner_extend_retentionbooleanoptional
Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end.
are_owners_notifiedbooleanoptional
Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end.
custom_notification_recipientsarray<UserMini>optional
A list of users notified when the retention policy duration is about to end.
assignment_countsobjectoptional
Counts the retention policy assignments for each item type.
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

retention_policy_id must identify the retention policy you want to retrieve. Each value in fields must name a retention policy attribute; specifying fields changes which standard attributes are returned.