Assign retention policy

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"
       }
     }'

client.retention_policy_assignments.create_retention_policy_assignment(
    retention_policy.id,
    CreateRetentionPolicyAssignmentAssignTo(
        type=CreateRetentionPolicyAssignmentAssignToTypeField.FOLDER, id=folder.id
    ),
)

await client.retentionPolicyAssignments.createRetentionPolicyAssignment({
  policyId: retentionPolicy.id,
  assignTo: {
    type: 'folder' as CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField,
    id: folder.id,
  } satisfies CreateRetentionPolicyAssignmentRequestBodyAssignToField,
} satisfies CreateRetentionPolicyAssignmentRequestBody);

try await client.retentionPolicyAssignments.createRetentionPolicyAssignment(requestBody: CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.id, assignTo: CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.folder, id: folder.id)))

client.getRetentionPolicyAssignments().createRetentionPolicyAssignment(new CreateRetentionPolicyAssignmentRequestBody(retentionPolicy.getId(), new CreateRetentionPolicyAssignmentRequestBodyAssignToField.Builder(CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.FOLDER).id(folder.getId()).build()))

await client.RetentionPolicyAssignments.CreateRetentionPolicyAssignmentAsync(requestBody: new CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.Id, assignTo: new CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.Folder) { Id = folder.Id }));

{
  "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",
    "max_extension_length": "365"
  },
  "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": "ceo@example.com"
  },
  "assigned_at": "2012-12-12T10:53:43-08:00",
  "start_date_field": "upload_date"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

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"
       }
     }'

client.retention_policy_assignments.create_retention_policy_assignment(
    retention_policy.id,
    CreateRetentionPolicyAssignmentAssignTo(
        type=CreateRetentionPolicyAssignmentAssignToTypeField.FOLDER, id=folder.id
    ),
)

await client.retentionPolicyAssignments.createRetentionPolicyAssignment({
  policyId: retentionPolicy.id,
  assignTo: {
    type: 'folder' as CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField,
    id: folder.id,
  } satisfies CreateRetentionPolicyAssignmentRequestBodyAssignToField,
} satisfies CreateRetentionPolicyAssignmentRequestBody);

try await client.retentionPolicyAssignments.createRetentionPolicyAssignment(requestBody: CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.id, assignTo: CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.folder, id: folder.id)))

client.getRetentionPolicyAssignments().createRetentionPolicyAssignment(new CreateRetentionPolicyAssignmentRequestBody(retentionPolicy.getId(), new CreateRetentionPolicyAssignmentRequestBodyAssignToField.Builder(CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.FOLDER).id(folder.getId()).build()))

await client.RetentionPolicyAssignments.CreateRetentionPolicyAssignmentAsync(requestBody: new CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.Id, assignTo: new CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.Folder) { Id = folder.Id }));

{
  "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",
    "max_extension_length": "365"
  },
  "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": "ceo@example.com"
  },
  "assigned_at": "2012-12-12T10:53:43-08:00",
  "start_date_field": "upload_date"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

This endpoint is not available on the Free Developer Plan. Upgrade here.

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.

FlowAuthorization Code

Authorization URL: https://account.box.com/api/oauth2/authorize
Token URL: https://api.box.com/oauth2/token

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.

Show child attributes

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.

Show child attributes

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.

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.

Show child attributes

assigned_to

object

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

Show child attributes

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.

Show child attributes

assigned_by

User (Mini) · object

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

Show child attributes

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"

Last modified on August 25, 2026

v2025.0

v2026.0

Assign retention policy

Authorizations

Body

Response