> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Companies

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.