Retention API

You can use the Retention API to decide how long the archive keeps your packages, and to review the packages whose time is up before anything is deleted. All paths start with /v2, and every call needs the headers in Common headers.

Your role decides which endpoints you can call. Permissions on each package still apply on top of that.

How retention works

A retention rule keeps a package for a set time, and then runs its end action. Here's the path a package takes:

1. You create a retention rule, and then you apply it to a package. A package can have only one rule: you can't apply a rule to a package that's already under retention or on legal hold.

2. The retention period starts when you apply the rule, or on a date in the package's metadata. The rule's duration decides when the period ends.

3. When the period ends, the archive runs the rule's end actions. It can delete the package, delete its content and keep its metadata, move it to the trash, or put it on a deletion list.

4. A deletion list collects the packages of one rule that reach the list in the same day, week, month, or year. Every night, the archive starts the review of each list whose period is over. You can also start a review sooner.

5. The reviewers that the rule names approve or deny the list, one after the other. When every reviewer approves, the archive runs the list's end action on each package on it.

A legal hold comes before retention. The archive doesn't run the end actions of a package on legal hold, and it waits until the hold is lifted. If you place a legal hold on a package that's on a deletion list, or extend its retention, the archive takes the package off the list.

Tip: To place or lift a legal hold, go to the Archive API.

List retention rules

Returns the retention rules in the archive, sorted by title.

GET /v2/retention/rules

Required role: archive-records-manager or archive-records-reviewer

Response: 200 OK with a paged list of RetentionRule objects.

Get a retention rule

Returns one retention rule.

GET /v2/retention/rules/{ruleId}

Required role: archive-records-manager or archive-records-reviewer

Response: 200 OK with a RetentionRule.

• 404 Not Found: there's no rule with this ID.

Create a retention rule

Creates a retention rule. After you create it, you can apply it to packages.

POST /v2/retention/rules

Required role: archive-records-manager

The body is a RetentionRule without the id. You always need startingPointPolicy. If endActions contains Document.DeletionList, you also need:

• deletionList.period

• deletionList.endAction

• At least one entry in deletionList.reviewers

This rule keeps a package for seven years after you apply it, and then puts it on a monthly deletion list. After two reviewers approve the list, the archive deletes the packages on it:

{
  "title": "Invoices, 7 years",
  "description": "Keep invoices for seven years, then review them before deletion.",
  "enabled": true,
  "startingPointPolicy": "immediate",
  "duration": {
    "years": 7
  },
  "endActions": ["Document.DeletionList"],
  "deletionList": {
    "period": "Period.Monthly",
    "reviewers": ["group:finance-records", "user:jdoe"],
    "userCanApproveMultiple": false,
    "endAction": "Document.Delete",
    "metadata": [
      {
        "label": "Title",
        "property": "dc:title"
      }
    ]
  }
}

Response: 200 OK with the RetentionRule that the archive created, including its id.

• 400 Bad Request with the reason REQUIRED_FIELD: startingPointPolicy is missing, or endActions contains Document.DeletionList and the deletion list settings aren't complete.

• 400 Bad Request with the reason INVALID_FORMAT: a deletionList.metadata property isn't in the prefix:field form.

• 400 Bad Request with the reason UNKNOWN_QUERY_FIELD: a deletionList.metadata property isn't a field that packages have.

• 400 Bad Request: startingPointPolicy has a value that isn't allowed.

Update a retention rule

Changes a retention rule. Send the full rule every time, with every field that you want it to keep, including the complete deletionList. To get the rule as it is, use Get a retention rule.

PUT /v2/retention/rules/{ruleId}

Required role: archive-records-manager

The body has the same fields and the same required fields as in Create a retention rule.

Response: 200 OK with the updated RetentionRule.

• 400 Bad Request: the same validation errors as when you create a rule.

• 404 Not Found: there's no rule with this ID.

Delete a retention rule

Deletes a retention rule. You can delete a rule when no package outside the trash has it, and when all its deletion lists are REMOVED.

DELETE /v2/retention/rules/{ruleId}

Required role: archive-records-manager

Response: 204 No Content.

• 404 Not Found: there's no rule with this ID.

• 409 Conflict with the reason RETENTION_RULE_IN_USE: the rule is still in use. The usedBy parameter says why: packages or deletionLists.

Apply a retention rule to a package

Puts a package under retention with the rule that you name.

POST /v2/archive/{packageId}/retention

Required role: archive-records-manager

{
  "ruleId": "6f1d2c8e-3b4a-4c5d-9e8f-0a1b2c3d4e5f"
}

For a metadata_based rule, the package must have a value in the date field that the rule's metadataXPath names. If that date plus the rule's duration is already in the past, the package is eligible for its end actions right away.

Response: 204 No Content.

• 400 Bad Request with the reason METADATA_FIELD_NOT_SET: the rule is metadata_based, and the package doesn't have the field. The field and packageId parameters name them.

• 404 Not Found: there's no package with this package ID.

• 409 Conflict: the package is already under retention or on legal hold.

Extend a package's retention

Sets a new end date for a package's retention. If the package is on a deletion list, the archive takes it off the list.

POST /v2/archive/{packageId}/retention/extend

Required role: archive-records-manager or archive-records-reviewer

{
  "newExpiryDate": "2034-12-31T23:00:00Z"
}

Response: 204 No Content.

• 400 Bad Request: newExpiryDate is missing or isn't a valid date and time.

• 404 Not Found: there's no package with this package ID.

List deletion lists

Returns the deletion lists, newest first. You can filter them by status, by rule, or by both.

GET /v2/retention/deletion-lists

Required role: archive-records-manager or archive-records-reviewer

Response: 200 OK with a paged list of DeletionList objects.

Get a deletion list

Returns one deletion list, with its status and its review steps.

GET /v2/retention/deletion-lists/{listId}

Required role: archive-records-manager or archive-records-reviewer

Response: 200 OK with a DeletionList.

• 404 Not Found: there's no deletion list with this ID.

List the packages on a deletion list

Returns the packages on a deletion list. Each package on a list is a record, with the date when its retention ended and the metadata values that the rule keeps.

GET /v2/retention/deletion-lists/{listId}/records

Required role: archive-records-manager or archive-records-reviewer

Response: 200 OK with a paged list of DeletionListRecord objects.

• 404 Not Found: there's no deletion list with this ID.

Export a deletion list as CSV

Downloads the records of a deletion list as a CSV file, for example to check the list outside the archive before you approve it.

GET /v2/retention/deletion-lists/{listId}/export

Required role: archive-records-manager or archive-records-reviewer

curl -o deletion-list.csv \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: $TENANT" \
  "https://archive.example.com/v2/retention/deletion-lists/$LIST_ID/export"

The file has one row per record, and these columns:

Response: 200 OK with the text/csv file as an attachment.

• 404 Not Found: there's no deletion list with this ID.

Start the review of a deletion list

Moves a deletion list from DRAFT to REVIEW. The archive does this every night for each list whose period is over, so you only need this call to start a review sooner.

POST /v2/retention/deletion-lists/{listId}/review

Required role: archive-records-manager or archive-records-reviewer

There's no request body. The list gets one review step for each entry in the rule's deletionList.reviewers, in the same order, and each step starts as OPEN.

Response: 200 OK with the DeletionList, with the status REVIEW.

• 400 Bad Request: the list isn't in DRAFT.

• 404 Not Found: there's no deletion list with this ID.

Approve or deny a deletion list

Records your decision for the review step that's waiting on the list. When the last step is approved, the archive runs the list's end action in the background, so the call returns before that's done. To follow it, get the list and check its status.

PUT /v2/retention/deletion-lists/{listId}/review

Required role: archive-records-manager or archive-records-reviewer

{
  "result": "DENIED",
  "reason": "Two invoices are part of an open audit."
}

The waiting step is the first one that isn't approved yet. You can decide on it if it names you (user:<username>), or a group that you're in (group:<group name>). Here's what each decision does:

• APPROVED: the step is approved, and the next step waits. After the last step, the list moves to APPROVED. When the end action has run on each package, the list shows REMOVED, with the time in removalTime.

• DENIED: the step is denied with your reason, and nothing is deleted. The list stays in REVIEW, and the same step keeps waiting, so a reviewer can still approve it later.

Response: 200 OK with the updated DeletionList.

• 400 Bad Request: result is missing, the list isn't in REVIEW, or the waiting step doesn't name you or one of your groups.

• 404 Not Found: there's no deletion list with this ID.

• 409 Conflict with the reason STATE_CONFLICT: you already approved another step of this list, and the rule's userCanApproveMultiple is false.

List active legal holds

Returns the packages that are on legal hold at the moment.

GET /v2/retention/legal-holds

Required role: archive-records-manager or archive-records-reviewer

Response: 200 OK with a paged list of LegalHold objects.

• 400 Bad Request with the reason INVALID_SORT: sortOrder isn't asc or desc.

Schemas

RetentionRule

RetentionDuration

The parts add up to one duration. A part that you leave out counts as 0.

DeletionListDefinition

DeletionList

DeletionListPeriod

DeletionListReview

DeletionListRecord

LegalHold

Paged lists

Every list endpoint in the Retention API returns the same wrapper around its items.