Skip to main content
The Paperless-ngx connector enables Omni to index and search documents stored in a Paperless-ngx instance via its REST API. OCR text, tags, correspondents, custom fields, and notes are all indexed.

​
Overview

​
What Gets Indexed

SourceContent
DocumentsFull OCR text extracted by Paperless-ngx
ClassificationCorrespondent, document type, tags, storage path, archive serial number
Custom fieldsResolved to human-readable field names
NotesUser annotations with author and timestamp
DatesCreated, 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
The connector is strictly read-only — it never modifies documents, tags, or metadata in your Paperless-ngx instance.

​
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
Use a dedicated service user with read-only permissions. See the Paperless-ngx API authorization docs for more details.

​
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
Your Paperless-ngx connector is now configured. Initial indexing time depends on the number of documents in your instance.

​
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

ModeDescription
FullFetches all documents from the instance (used for initial sync)
IncrementalFetches 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

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.
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.

​
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

Search Your Data

Learn how to search across your documents

AI Assistant

Ask questions about your scanned documents

Add More Connectors

Connect additional data sources