API Explorer

Data Retention

Data Retention

A retention policy says how long one kind of record in a space stays live, and what happens to it then. The space is a bank, or SYS for the system space. Periods are set per space through the API, never in code.

A policy covers one resource type: Dynamic Entity records (of one entity), files, chat messages, chat rooms, customers or consents. It says:

  • what the period is counted from, for example when the record was created, last updated, or a date held in one of its fields;
  • optionally, a condition, so that only records with a given value in a field are covered, for example a status of CLOSED;
  • how many days a record stays live: at least retention.minimum_retain_days (five years by default);
  • what then happens: archive (moved out of the live tables into the retention archive, and deleted after a further period), delete, or, for customers only, anonymise (the personal fields are cleared, and the customer id is kept so that references stay valid);
  • whether a second, different person must approve each run.

A scheduler runs the enabled policies, and a run can also be started by hand. Preview a policy first to see what it would affect. Records on legal hold are skipped by every run, and every disposal is written to the disposal register. Nothing is restored from the archive. Archiving needs retention.archive.enabled=true, and deleting or anonymising needs retention.delete.enabled=true.

The Roles are granted at the space: CanManageRetentionPolicy, CanGetRetentionPolicies, CanRunRetentionPolicy, CanApproveRetentionRun, CanGetRetentionRuns, CanManageRetentionHold and CanGetRetentionArchive.

Endpoints