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

# Paperless-ngx

> Connect a Paperless-ngx instance to Omni for unified search across scanned and OCR'd documents

The Paperless-ngx connector enables Omni to index and search documents stored in a [Paperless-ngx](https://docs.paperless-ngx.com/) instance via its REST API. OCR text, tags, correspondents, custom fields, and notes are all indexed.

## Overview

### What Gets Indexed

| Source         | Content                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| Documents      | Full OCR text extracted by Paperless-ngx                                |
| Classification | Correspondent, document type, tags, storage path, archive serial number |
| Custom fields  | Resolved to human-readable field names                                  |
| Notes          | User annotations with author and timestamp                              |
| Dates          | Created, added, and modified timestamps                                 |

### How It Works

1. You provide a Paperless-ngx base URL and API token
2. The connector fetches documents via the Paperless-ngx REST API
3. Full syncs retrieve all documents; incremental syncs fetch only documents modified since the last run
4. Incremental state is checkpointed periodically so large syncs can resume

<Note>
  The connector is strictly read-only — it never modifies documents, tags, or metadata in your Paperless-ngx instance.
</Note>

## Prerequisites

Before setting up the Paperless-ngx connector, ensure you have:

* **Paperless-ngx instance** reachable from the Omni network
* **An API token** with read access to documents, tags, correspondents, document types, storage paths, and custom fields
* **Omni deployment** with the Paperless connector service running (profile: `paperless`)

## Setup

### Step 1: Create an API Token

1. Sign in to Paperless-ngx as the user Omni will connect as
2. Go to **Settings** → **API** → **API Tokens**
3. Create a new token and copy it — it will only be shown once

<Tip>
  Use a dedicated service user with read-only permissions. See the [Paperless-ngx API authorization docs](https://docs.paperless-ngx.com/api/#authorization) for more details.
</Tip>

### Step 2: Connect in Omni

1. Navigate to **Settings** → **Integrations** in Omni
2. Find **Paperless-ngx** and click **Connect**
3. Enter the connection details:
   * **Base URL**: Your Paperless-ngx instance (e.g. `https://paperless.example.com`)
   * **API Key**: The token from Step 1
4. Click **Connect**
5. Click **Sync Now** to start the initial sync

<Check>
  Your Paperless-ngx connector is now configured. Initial indexing time depends on the number of documents in your instance.
</Check>

## Managing the Integration

### Viewing Sync Status

Navigate to **Settings** → **Integrations** to view last sync time, number of indexed documents, and any errors. Click **Configure** for details.

### Sync Modes

| Mode            | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| **Full**        | Fetches all documents from the instance (used for initial sync)                  |
| **Incremental** | Fetches only documents modified since the last sync (tracked via `last_sync_at`) |

Incremental state is checkpointed periodically so syncs can resume if interrupted.

### Removing the Integration

1. Navigate to **Settings** → **Integrations**
2. Click **Configure** against the Paperless-ngx source
3. Click **Delete Permanently**

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    The API token is incorrect, expired, or lacks the required permissions.

    **Solution**: Verify the token in Paperless-ngx at **Settings** → **API** → **API Tokens** and regenerate if needed. Ensure the token's user has read access to documents and their related resources.
  </Accordion>

  <Accordion title="Documents not appearing in search">
    Common causes:

    * Sync has not yet completed
    * The API token's user doesn't have permission to view the documents

    **Solution**: Check the sync status in **Settings** → **Integrations** → **Paperless-ngx** and verify the user's permissions in Paperless-ngx.
  </Accordion>

  <Accordion title="Custom fields missing">
    Custom fields are resolved through a separate API call. If the token lacks access to the custom fields endpoint, they will not appear.

    **Solution**: Grant the token's user read access to custom fields in Paperless-ngx.
  </Accordion>
</AccordionGroup>

## Security Considerations

* **Read-only access**: The connector only issues `GET` requests to the Paperless-ngx API
* **API tokens**: Use a dedicated service user and token so access can be revoked independently
* **Encrypted storage**: Credentials are encrypted at rest in Omni

## What's Next

<CardGroup cols={3}>
  <Card title="Search Your Data" icon="magnifying-glass" href="/user-guide/search">
    Learn how to search across your documents
  </Card>

  <Card title="AI Assistant" icon="robot" href="/user-guide/ai-assistant">
    Ask questions about your scanned documents
  </Card>

  <Card title="Add More Connectors" icon="plug" href="/connectors/overview">
    Connect additional data sources
  </Card>
</CardGroup>