home-assistant.io/source/_integrations/paperless_ngx.markdown

title, description, ha_release, ha_category, ha_iot_class, ha_config_flow, ha_domain, ha_codeowners, ha_integration_type, ha_quality_scale, related, ha_platforms

title	description	ha_release	ha_category	ha_iot_class	ha_config_flow	ha_domain	ha_codeowners	ha_integration_type	ha_quality_scale	related	ha_platforms
Paperless-ngx	Instructions on how to integrate Paperless-ngx into Home Assistant	2025.6	Sensor	Local Polling	true	paperless_ngx	@fvgarrel	service	silver	url title https://docs.paperless-ngx.com/ Paperless-ngx	diagnostics sensor

The Paperless-ngx {% term integration %} allows you to connect your Paperless-ngx instance to Home Assistant and monitor its status and activity.

Prerequisites

{% important %} This integration is only fully supported with Paperless-ngx version 2.15 or later. Earlier versions are not supported. {% endimportant %}

To ensure full functionality of this integration, you must have read permissions for all document-related resources, including documents, tags, document types, and correspondents.

To enable monitoring of diagnostic sensors, you must have administrator permissions. Without administrator rights, specific API endpoints cannot be accessed, and the sensor states will not be available.

{% details "Create an access token" %}

1. Log in to your Paperless-ngx instance.
2. In the upper-right corner, select your profile icon.
3. Select My Profile.
4. Under API Auth Token, select the right Refresh button next to the textbox to generate a new token. Confirm with yes.
5. Copy the token and use it during the integration setup in Home Assistant.

{% enddetails %}

{% include integrations/config_flow.md %}

{% configuration_basic %} URL: description: "URL to connect to the Paperless-ngx instance." API key: description: "API key to connect to the Paperless-ngx API." {% endconfiguration_basic %}

Sensors

This integration provides {% term sensors %} for the following information from Paperless-ngx:

Sensor	Description
Correspondents	Indicates the total number of defined correspondents.
Document types	Indicates the total number of defined document types.
Documents in inbox	Indicates the number of documents currently in the inbox.
Tags	Indicates the total number of defined tags
Total characters	Indicates the total number of characters extracted from all documents.
Total documents	Indicates the total number of documents stored.
Total storage	Indicates the total disk space used by Paperless-ngx.
Available storage	Indicates the remaining available disk space for Paperless-ngx.
Status database	Indicates whether the database is reachable and functioning correctly.
Status index	Indicates whether the document indexing service is operational.
Status classifier	Indicates whether the document classifier service is running properly.
Status celery	Indicates whether the Celery task queue is active and processing tasks.
Status redis	Indicates whether the Redis service used for task queuing is available.
Status sanity	Indicates the sanity of the Paperless-ngx documents.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

{% include integrations/remove_device_service.md %}