Estimated reading time: 9 minutes
Smart home meets digital order - on your own server.
If you use Home Assistant for your smart home and Paperless-NGX for digital document management, you can create a real automation powerhouse by combining them. In this article, I'll show you how to combine the two tools in a meaningful way - simply, efficiently and securely.
For detailed instructions and an explanation of all configuration options, I recommend the YouTube video linked below. In this video, every single setting is explained in detail so that you receive comprehensive instructions for the exact setup. You can find any code from the video in this article so that you can use it directly without having to type it in.
🔧 Warum diese Kombination Sinn ergibt
Home Assistant is the control center of your smart home - you control everything from lighting to security. Paperless-NGX, on the other hand, helps you to tame the flood of paper and manage documents digitally. Together, they give you maximum control over your digital home - including automated workflows.
Imagine this: A new invoice arrives by email or is scanned. Paperless-NGX automatically recognizes the provider, the date and the amount. At the same time, Home Assistant informs you about it - or even triggers actions:
- Light notification for new invoice
- Push message for tax documents
- Reminder in the calendar for payment deadlines
- Automatic upload of documents to the cloud or your NAS
What is Paperless-NGX?
Paperless-NGX is a powerful, self-hosted document management system (DMS) that helps you bring order to your digital document chaos. It is based on the original open source project "Paperless" and has been further developed under the name "Paperless-NGX" as a modernized, actively maintained and greatly improved version.
Here to the Paperless-NGX installation.
🧾 Die Grundidee: Dokumente digital erfassen & durchsuchbar machen
With Paperless-NGX, you can manage all your paper-based or digital documents centrally. Whether scanned invoices, letters, contracts or PDF documents sent by email - everything is stored in a structured way, automatically indexed and made searchable using OCR (Optical Character Recognition). It doesn't matter whether the document comes from the scanner, was uploaded as a PDF or is forwarded to Paperless by e-mail.
🧠 Intelligente Texterkennung mit OCR
A key feature is the integrated text recognition. Thanks to OCR, content is read automatically - even from handwritten or poorly scanned documents (depending on the quality). This allows you to search not only for file names, but also for content - e.g. the name of a sender, an invoice number or a specific amount.
🏷️ Automatisches Tagging & Dokumentenklassifizierung
Paperless-NGX uses Consumers - These are small rules or scripts that automatically recognize, tag, categorize and archive documents. For example, the system recognizes that a certain PDF is an electricity bill from your supplier and assigns it to the category "ancillary costs", tags it with "electricity" and files it in the appropriate year.
You can customize the rules - either through simple user interfaces or through regular expressions (RegEx) if you want to go deeper.
📥 Mehrere Importquellen möglich
Documents enter Paperless-NGX in various ways:
- Direct upload via the web interface
- Automatic import from a local folder (e.g. from the scanner)
- E-mail import via a dedicated IMAP interface
- API upload by other applications
This allows you to configure your scanner or multifunction printer, for example, so that it transfers documents directly to Paperless-NGX - fully automatically.
🗃️ Suchfunktion & Filter
The intuitive web interface offers you a powerful search function with various filters - by date, category, keyword, source, document type and much more. So you can find any document in seconds - even years later. Ideal for tax returns, guarantees or contract reviews.
🔒 Datenschutz & Selbst-Hosting
A big advantage: Paperless-NGX runs completely locally on your premises - e.g. on a NAS, Raspberry Pi, Linux server or via Docker. You retain full control over your data. No cloud, no external provider, no subscription costs. Ideal for anyone who values Data protection and digital sovereignty lay.
🧩 Erweiterbar & API-freundlich
Thanks to a well-documented REST API, you can easily integrate Paperless-NGX with other systems - such as Home AssistantZapier, n8n or individual scripts. This allows you to implement clever automations - from the light signal for new invoices to automatic forwarding to your tax advisor.
What is Home Assistant?
Home Assistant is an open source platform for home automation that aims to connect and centrally control all devices in the home. It is designed to provide a unified user interface and simple, flexible control for a variety of smart home devices from different ecosystems. Here are some points in favor of Home Assistant:
- CompatibilityHome Assistant supports thousands of devices and services from various manufacturers, including lighting, air conditioning, heating, cameras, weather sensors, voice assistants and more.
- Local controlUnlike many commercial smart home platforms that rely on cloud services, Home Assistant runs locally on your network. This means increased privacy and reliability, as your smart home devices work even without an active internet connection.
- Automation and scenesOne of the main features of Home Assistant is the ability to create complex automations and scenarios. For example, you can have lights switch on automatically when it gets dark or turn on the heating when the temperature falls below a certain level.
- Simple user interfaceHome Assistant offers a user-friendly interface that makes it easy to monitor and control devices. This interface is fully customizable.
- Integration with voice assistantsHome Assistant can be integrated with voice assistants such as Amazon Alexa or Google Assistant to enable voice-controlled control of your smart home devices.
- Open source and community-drivenSince Home Assistant is open source, it is supported by an active community that is constantly developing new integrations and improving existing ones.
- Data protection and securityAs a locally running platform, Home Assistant has the advantage that the data remains within its own network. This protects privacy and increases security compared to cloud-based solutions.
In summary, Home Assistant is a powerful and flexible solution for those who want to design their own smart home and control their devices centrally, regardless of the manufacturer or ecosystem.
⚙️ So integrierst du Paperless-NGX in Home Assistant
- Set up Paperless-NGX with Docker
It is best to install Paperless-NGX via Docker-Compose on the same server on which Home Assistant is running (e.g. on a Raspberry Pi, Intel NUC or a home server). You can find a suitable article and video on this here: Paperless-NGX - Use integration (more on this in the rest of the article):
Recently, there has been an official integration of Paperless-NGX for Home Assistant.
- Using the REST API
Paperless-NGX offers a modern REST API that you can integrate with Home Assistant. A simple way to integrate with Home Assistant is therest-sensor orhttp-sensor. Example:
sensor:
- platform: rest
name: "Documents in inbox"
resource: http://192.168.178.29:8001/api/documents/?correspondent__isnull=true
value_template: "{{ value_json.count }}"
scan_interval: 300This allows Home Assistant to regularly read the status of your paperless inbox. The advantage of custom REST sensors is that you can customize them even more. But it's also more complicated.
🚀 Alle verfügbaren Sensoren und Features
The integration provides a variety of sensors that give you real-time insights into the status of your Paperless ngx system:
correspondents- Number of defined contact persons (correspondence partners)document_types- Number of defined document typesdocuments_inbox- Number of current documents in the inbox folder (Inbox)tags- Number of defined tagstotal_characters- Total number of characters extracted via OCRtotal_documents- Total number of all saved documentstotal_storage- Total memory used by Paperless-ngxavailable_storage- Storage space still availablestatus_database- Status of the database (accessible/error-free)status_index- Status of the document indexerstatus_classifier- Status of the classifier (automatic tagging/classifier service)status_celery- Status of the Celery task queue (processing)**status_redis- Availability of the Redis service (for task queue)status_sanity- Result of the "Sanity Checks" on your documents
⚙️ Wichtige Voraussetzungen & Hinweise vor der Nutzung
- 🔐 At least Paperless-ngx 2.15
- Older versions are not supported. - 📚 Read rights (permissions)
- You need read rights for documents, tags, document types and correspondence partners. - 🛠 Admin rights recommended
- Without admin access you are missing diagnostic sensors (e.g. status: database, celery, redis etc.). - 🧾 Create API token
- Log in to Paperless-ngx → Profile → Generate API Auth Token → Use for integration in Home Assistant
🛠 So richtest du die Integration ein
- Settings → Devices & Services → Add Integration
- Search for Paperless-ngx
- Enter the URL of your instance (e.g.
http://192.168.178.29:8001) and the API token in.
💡 Nutzung & Integrationsmöglichkeiten
- Dashboard functionality:
Build an overview panel, e.g. in Lovelace, with the inbox and status sensors. - Automations:
Trigger based on:sensor.documents_inbox > 0status_*(e.g.status_database == 'OFFLINE'for failure warnings)
- Performance monitoring:
Monitor storage space, index status and OCR classifier directly in Home Assistant. - Fault alarm:
Be notified of LDAP/DB failures (e.g.status_database,status_celery).
🔔 Automation: Benachrichtigung bei neuen Dokumenten
Want to know immediately when new documents have been scanned or uploaded? With this automation, you'll receive a push notification as soon as there are new files in your Paperless inbox - and the time-delayed after 5 minutesto avoid unnecessary alarms.
alias: Paperless new documents
description: Notification when Paperless receives new documents
trigger:
- platform: numeric_state
entity_id: sensor.http_192_168_178_29_8001_dokumente_im_posteingang
above: 0
for:
minutes: 5
action:
- service: notify.smartphones
data:
title: Paperless has documents
message: You have mail.
data:
notification_icon: mdi:file-document-plus
channel: Emergency
importance: max
priority: high
ttl: 0
color: orange
timeout: 64800
mode: single🧠 Erklärung:
trigger: As soon as there are more than 0 documents in the inbox and for longer than 5 minutestriggers the automation.actionThe message is pushed to your connected smartphones - including high priority, color and icon.- You can of course also Add further actionse.g. LED notifications, voice output via TTS or display on a dashboard.
🔗 Weitere Möglichkeiten & Ideen
- 📅 Automatische Erinnerung bei Fristen (Versicherungen, Rechnungen, Steuer)
- 📠 Integration deines Netzwerkscanners als Trigger für die Paperless-OCR-Verarbeitung
- 💡 NFC-Tag-gestützte Scans: Dokumente einscannen durch einfaches Tippen mit dem Smartphone
YouTube video implementation
Conclusion
With the combination of Home Assistant and Paperless-NGX you create a fully automated, data-sovereign workflow. You always know whether important documents have arrived - without having to constantly open the web interface. Thanks to Home Assistant, you can also fully customize this process to your everyday life - according to your rules.
Wenn du bereits beide Tools nutzt, ist diese Integration ein absoluter No-Brainer. Wenn nicht – ist jetzt der perfekte Zeitpunkt, damit zu starten. 🚀
0 Comments