> This documentation belongs to Invofox, an AI-powered document processing
> platform. The API extracts structured data (fields) from unstructured
> documents (invoices, contracts, forms, bank statements, and more).
> Key concepts: Account, Environment, Document Type, Field, File, Import,
> and Document. When answering, prefer the exact terminology defined in the
> Glossary and cite the relevant API Reference endpoint when applicable.

# Processing Tracking

> Track the status of imports, files, and documents in Invofox using a simplified state system together with webhook events.

Invofox tracks the main elements mentioned in our [core concepts](/documentation/glossary#ingestion) through a simplified state system:

- **Imports**: Operations processing one or more files
- **Files**: Individual uploaded files
- **Documents**: Processed outputs with extracted data

Each element progresses through clearly defined states, generating webhook events when states change. This provides real-time visibility into your document processing pipeline.

For API endpoints to retrieve current state information, see [Information Retrieval](/api-reference/information-retrieval).

## Import Processing

### States and Transition Logic

- `processing` - Import created and files are being processed
- `processed` - All files have finished processing (either processed or rejected)

**Transition Logic:** An Import moves to `processed` when every File in the Import has reached either `processed` or `rejected` state.

### Import Lifecycle

Only the `processed` state triggers webhook events for Imports.

```mermaid
stateDiagram-v2
    direction LR
    [*] --> processing : Import Created
    processing --> processed : All Files processed
    processed --> [*]

    classDef processing fill:#e1f5fe
    classDef final fill:#c8e6c9

    class processing processing
    class processed final
```

### Webhook Events

- `import.processed` - Triggered when an Import reaches `processed` state

## File Processing

### States and Transition Logic

- `pending` - File registered from Import or extracted from ZIP
- `processing` - File ingested and being processed internally
- `rejected` - File rejected before processing (invalid format, configuration issues, corruption)
- `processed` - File has generated Documents and all Documents are processed

**Transition Logic:** A File moves to `processed` when:

- **Single Document:** The associated Document reaches `processed` state
- **Multiple Documents (Splitter):** All associated Documents reach `processed` state
- **ZIP File:** All extracted Files reach either `processed` or `rejected` state

### File Lifecycle

Webhook events are triggered when Files reach final states: `rejected` or `processed`.

```mermaid
stateDiagram-v2
    [*] --> pending : File Registered
    pending --> processing : File ingested
    processing --> rejected : Invalid/corrupted
    processing --> processed : All Documents processed
    rejected --> [*]
    processed --> [*]

    classDef pending fill:#fff3e0
    classDef processing fill:#e1f5fe
    classDef rejected fill:#ffcdd2
    classDef final fill:#c8e6c9

    class pending pending
    class processing processing
    class rejected rejected
    class processed final
```

### File Error Codes

When a File reaches `rejected` status, it includes an `error` field with a specific error code (for example `ERR_UNSUPPORTED_FILE_FORMAT`). See the complete, up-to-date list in [Rejected files](/documentation/rejected-files#error-codes).

### Webhook Events

- `file.rejected` - Triggered when a File reaches `rejected` state
- `file.processed` - Triggered when a File reaches `processed` state

## Document Processing

### States and Transition Logic

Documents have two state systems:

**Processing Status (internal):**

- `processing` - Document assigned ID and being processed
- `processed` - Automatic processing completed

**Public States (workflow):**

- `pendingCorrection` - Document awaiting manual corrections or review
- `approved` - Document approved (manual or automatic)
- `discarded` - Document discarded (manual or automatic)
- `processing` - ⚠️ **Deprecated** - Legacy public state, use processing status instead
- `exported` - ⚠️ **Deprecated** - Legacy exported state
- `error` - ⚠️ **Deprecated** - Legacy error state

> **Note:** The document workflow system including `publicState` field and related events (`approved`, `discarded`, `updated`) is currently being reevaluated and refined. Implementation details may change in future versions.

**Transition Logic:** A Document moves from `processing` to `processed` status when all automatic extraction and processing logic completes. Separately, documents can be assigned public workflow states (`pendingCorrection`, `approved`, `discarded`) for business process management.

### Document Lifecycle

Webhook events are triggered for both processing states and public workflow states.

**Processing Status Flow:**

```mermaid
stateDiagram-v2
    [*] --> processing : Document Assigned ID
    processing --> processed : Extraction completed
    processed --> [*]

    classDef processing fill:#e1f5fe
    classDef processed fill:#c8e6c9

    class processing processing
    class processed processed
```

**Public State Flow (separate from processing):**

```mermaid
stateDiagram-v2
    [*] --> pendingCorrection : Requires review
    [*] --> approved : Auto-approved
    [*] --> discarded : Auto-discarded
    pendingCorrection --> approved : Manual approval
    pendingCorrection --> discarded : Manual discard
    approved --> [*]
    discarded --> [*]

    classDef pending fill:#fff9c4
    classDef approved fill:#a5d6a7
    classDef discarded fill:#ffab91

    class pendingCorrection pending
    class approved approved
    class discarded discarded
```

### Webhook Events

**Processing Events:**

- `document.created` - Triggered when a Document is created and immediately enters `processing` status
  - Document is assigned an ID and enters the processing pipeline
  - **Note:** There are no intermediate states - the document is created and immediately transitions to `processing` status. At this point the document will be empty. The API will return a 202 Accepted status indicating the document is reserved but not yet available for retrieval. Full document data will be available after `document.processed` event.
- `document.processed` - Triggered when a Document reaches `processed` status
  - Automatic extraction and processing completed
  - Document status becomes `processed`
  - Contains all extracted information

For webhook configuration and implementation details, see [Webhook Implementation](/webhooks-reference/webhook-implementation).

## Special Cases

These special processing scenarios affect how state transitions work for complex file types and configurations.

### Document Splitting

When a File generates multiple Documents (e.g., multi-page PDF):

1. File is in `processing` state while being processed, which results in Document creation
2. Each Document follows independent lifecycle
3. File reaches `processed` only when all Documents reach `processed` state

This splitting can happen automatically using Invofox's [Splitter](/documentation/glossary#splitter) premium feature, which intelligently detects document boundaries and creates separate Document records.

The File's metadata will include information about page splits as shown in [ImportInfo Structure](/api-reference/information-retrieval#importinfo-structure).

For Document state details and API structure, see [Document Structure](/api-reference/information-retrieval#document-structure).

### ZIP Files

When a ZIP file is uploaded through multiple file upload endpoints:

1. ZIP file is accepted and immediately moves from `pending` to `processing` status
2. ZIP is extracted, creating child Files
3. Parent File reaches `processed` only when all child Files reach `processed` or `rejected`
4. Child Files follow normal File lifecycle independently

**Important:** ZIP files are only supported through multiple file upload endpoints (Direct Upload and URL Upload). ZIP files are processed asynchronously and transition directly to `pending` state upon acceptance.

For advanced ZIP processing workflows, you can combine [Splitter + Classifier](/documentation/glossary#classifier) premium features to automatically separate and identify different document types within ZIP archives.

The parent File's `file.processed` event will include information about all extracted child Files. For compressed file metadata structure, see [File API Structure](/api-reference/information-retrieval#file-structure).