Erase organisation (post-window)

POSThttps://app.speybooks.com/api/v1/admin/orgs/{id}/erase

Erase an organisation and all of its org-scoped data after its seven-year retention window has closed.

This is a controller disposal at retention-window close, the discharge of the custodial commitment SpeyBooks holds on the customer's behalf. It is not an Article 17 right-to-be-forgotten: the organisation's owner is not a data subject with respect to their own company's books. The window is SpeyBooks' seven-year custodial commitment, measured from the latest accounting period end, held above the six-year HMRC and VAT statutory minimum rather than equal to it.

The erasure is irreversible. It runs as two committed steps. The first records a disposal tombstone carrying the organisation's terminal audit chain head, so a holder of a prior export can verify their records hash forward to it. The second sets a per-transaction sanction for this organisation's id and deletes it; the org-scoped foreign keys cascade and remove the whole subtree. The tombstone carries no foreign key to the organisation, so it survives.

Idempotent under crash recovery: if the routine is interrupted between the two steps, the durable tombstone is found on a re-run and the deletion completes without re-recording.

Request Body

  • note: optional free-text for the audit trail, minimum 5 characters.

Records an ORG_ERASED action in the audit log, which is not org-scoped and so survives the erasure.

The OpenTimestamps receipt on the tombstone is deferred: it is written null and backfilled when OpenTimestamps ships as its own item. The audit chain head is the cryptographic tombstone in the interim (ADR-023 addendum).

Refusals (no data is touched):

  • 422 RETENTION_WINDOW_OPEN: the window has not closed. The response carries the close date. Deactivate instead to lock the organisation out now.
  • 422 RETENTION_WINDOW_INDETERMINATE: the organisation has no accounting period to anchor the window from, so closure cannot be proven. Close a period first, or deactivate if genuinely empty.

Error responses:

  • 404 NOT_FOUND: no organisation with that id, and no record of one having been erased.
  • 409 ALREADY_ERASED: the organisation has already been erased.

Path parameters

idstringrequired
Organisation ID.

Body parameters

notestringoptional
Optional free-text note (audit trail only). Min 5 characters.
min length: 5

Response

200Organisation erased, or an interrupted erasure resumed and completed.
Show response fields
auditChainHeadstring
gdprRequestIdstring
messagestring
resumedboolean

Error codes

404Organisation not found.
409Organisation has already been erased.
422Retention window open, or indeterminate; erasure refused, no data touched.