Soft Deletion

WatchEye preserves a record of every entity, program, monitor, note and related artefact for compliance and audit purposes. To make that possible, all DELETE endpoints in the API are soft deletes rather than physical deletes.

What "soft-deleted" means

A soft-deleted record is hidden from both the API and the portal but remains in the database:

• The record is no longer returned by GET list endpoints.
• The record's individual GET /<resource>/{uuid} endpoint returns 404 Not Found.
• POST / PATCH calls that reference the record by UUID return 404 Not Found.
• Where a record has dependents (e.g. deleting a program also soft-deletes its entities, checks, ID checks, reports, events and notes), the dependent records are hidden in the same way.
• The original DELETE call returns the deleted record's representation once as confirmation. Subsequent calls return 404.

Recovery window

Soft-deleted records can be restored within 30 days of deletion. Restoration is currently a portal-only action: a user with the account manager role can navigate to the relevant list (e.g. Programs, Entities, Monitors), apply the "Show deleted" filter, open the record and choose Restore. There is no API equivalent of the restore action.

After the 30-day window, soft-deleted records are eligible for permanent removal and may be purged from the database without notice. Once purged, the record and its UUID cannot be recovered.

If you need to retain a record beyond 30 days but no longer want it surfaced in your normal workflows, archive it instead of deleting it (where the resource supports archiving) or use the appropriate status / flags fields to mark it as inactive.

What is and isn't soft-deleted

PATCH calls that change a status field (e.g. program.status = "paused", monitor.status = "paused") are not deletions; the affected record remains fully visible via the API.

Prefer archiving over deletion for compliance

If you only need to take a record out of day-to-day workflows but must keep it accessible for compliance, audit or historical reporting, archive it instead of deleting it. Archived records are not subject to the 30-day recovery window - they are retained indefinitely.

The differences:

Archive support per resource:

Archiving an entity also cascades to its identification checks and reports. Checks, events and notes do not have a per-record archive action - their archive state always follows the entity they belong to. Programs do not support archiving; if you need to take a program out of day-to-day workflows you can set its status to paused (scheduled monitor runs and event report emails will skip paused programs).

Reference numbers and soft-deleted entities

Entity reference_number values must be unique among non-deleted entities in the same program. Soft-deleted entities are excluded from that check.

Example: you DELETE an entity with reference_number = "00-000-001". While that record remains soft-deleted (including throughout the 30-day recovery window), you may POST a new entity in the same program with reference_number = "00-000-001". The API accepts the create because the deleted row no longer counts toward uniqueness.

The same reference_number may also be used on a different program while the soft-deleted copy still exists, because uniqueness is scoped per program.

After the recovery window, the soft-deleted record may be purged. Whether or not it has been purged, creating a new entity with that reference_number in the same program remains valid as long as no other non-deleted entity in that program already uses it.

Implications for integrators

• Treat a 404 on a UUID you previously saw as "the record may have been deleted" rather than "the UUID was never valid". The 30-day recovery window gives you time to coordinate with the account owner if the deletion was unintended.
• For how reference_number interacts with soft deletes, see Reference numbers and soft-deleted entities above.
• If you need a confirmed-permanent removal (for example to satisfy a customer's data-erasure request), contact the Global Data support team. Permanent removal is a manual operation handled outside the API.