Read company identity and lifecycle metadata, then reset a Sandbox when you need
to rebuild its test data. Lifecycle reads require company.view; Reset requires
company.reset. A caller may read lifecycle while being denied Reset.
Use GET /api/v1/companies/{companyId}/lifecycle to inspect the mode, Owner,
Purpose, Reset eligibility and reason, and last Reset. Only initialized Sandbox
companies can be reset. Live and Retired companies are protected for every caller.
POST /api/v1/companies/{companyId}/reset permanently clears application data
including soft-deleted entities, financial records, forms and packets, file
references, tasks, runs, and operational history. It keeps configuration versions
and drafts, all financial configuration, form templates, file categories, invoice
audit rules, email intake setup, saved views, export presets, company metadata,
API contacts, rollout overrides, users, roles, memberships and API keys. Sequence
definitions are retained; numbering restarts at each configured start number.
Company lifecycle receipts, staff access history and minimal Reset receipts remain.
The response is synchronous with deleted row counts and restarted counters. All
database deletions, counter updates and the Reset receipt commit in one transaction;
a failure rolls them back together. Other companies and companyless audit history
are untouched. Cloud storage objects are not deleted.
Stop other Sandbox activity before Reset: concurrent writes can repopulate data.
There is no background job or request replay guarantee. If you lose the response,
inspect lifecycle and its last Reset before deciding whether to retry. An optional
agentLabel identifies your automation in the receipt; it is a self-supplied label.
The same operation is available in app Admin → Data Management and Control
Plane Companies → Actions → Reset Sandbox, with a persistent warning and one click.
