Paperless-ngx with n8n: Automatically Sort and Forward Receipts

Paperless-ngx can be connected to n8n in two ways: the post-consume hook, which starts a script after a document has been consumed, and the REST API, through which n8n can query documents, tags, and metadata or upload new receipts. For handing documents over to accounting, this usually means in practice that a post-consume script calls an n8n webhook, and n8n then fetches the complete document data via the REST API afterward, instead of sending all the information in the first call. A well-known pitfall here is the file upload from n8n to Paperless-ngx, which fails with a 415 error if configured incorrectly. As of: August 2026.

How does a post-consume script trigger an n8n workflow?

According to its own documentation, Paperless-ngx allows you to run a custom script after document processing is complete, which gets access to metadata such as DOCUMENT_ID, DOCUMENT_CORRESPONDENT, DOCUMENT_TAGS, and DOCUMENT_ARCHIVE_PATH via environment variables. The script explicitly cannot abort the processing, and it should not modify the document files itself, since it runs synchronously and would otherwise delay consumption. In a Docker Compose installation, you mount the script directory as a volume and set the PAPERLESS_POST_CONSUME_SCRIPT environment variable to the path inside the container. The simplest script uses the passed variables to call the production URL of an n8n webhook node via curl, passing the document ID and tags as JSON. Details on the available variables can be found in the Paperless-ngx advanced usage documentation.

How does n8n upload or retrieve receipts via the Paperless-ngx REST API?

The Paperless-ngx REST API authenticates via a token, which you either generate in the profile section of the web interface or request programmatically via a POST to /api/token/ with a username and password; you then pass it in the Authorization: Token <token> header. To upload a document, n8n calls the /api/documents/post_document/ endpoint as a multipart-formatted form and can optionally include fields such as title, correspondent, document_type, storage_path, and multiple tags, while Paperless-ngx immediately returns the UUID of the consumption task upon a successful start. To read out existing receipts, the /api/documents/ endpoint is available with search and filter parameters such as text= or query=. Details on authentication and endpoints can be found in the Paperless-ngx API documentation.

Why does the file upload fail with a 415 error?

In a documented case from the n8n community, uploading a PDF from Google Drive to a local Paperless-ngx instance failed with the message "Unsupported media type 'application/pdf' in request", because the HTTP Request node had not sent the file in the multipart/form-data format expected by the API. The user solved the problem by reconfiguring the request based on the official API documentation instead of transferring the binary file directly in raw format. Therefore, explicitly check in the HTTP Request node that the body type is set to multipart-form-data and not to a generic JSON or binary body, before linking the field with the binary file from a previous node. In practice, this error mainly occurs when first setting up the integration and is not a recurring problem afterward.

How do you automatically assign tags, and how do things then move on to accounting?

Paperless-ngx assigns tags via configurable matching algorithms, including Any, All, Exact, Regex, Fuzzy, and Auto, where Auto is based on a model trained on existing documents and works entirely without manual rules. For handing over to accounting, the n8n workflow reads the document data, including the assigned tags, via the REST API after the webhook trigger, and forwards receipts with a matching tag, such as "incoming invoice" or "travel expenses", to an accounting system via an HTTP Request node or to the responsible person via an email node. This creates a seamless process from scanning or email import all the way to filing in the accounting system, without anyone having to sort receipts manually. NordFlux builds such handover workflows individually for clients as part of n8n automation, usually supplemented with an error notification for receipts that cannot be assigned.

Frequently asked questions about n8n with Paperless-ngx

Do I absolutely need the post-consume hook, or is the REST API alone enough?

The REST API alone is enough if you want to poll n8n regularly for new documents, but the post-consume hook is the more direct route, because Paperless-ngx then actively triggers a workflow itself. In practice, the combination of both delivers the most reliable results, because the hook provides the timing and the API provides the complete data.

Why does the file upload to Paperless-ngx in n8n often fail?

The most common reason is an incorrectly configured body type in the HTTP Request node, which does not transmit the file as multipart/form-data, as required by the /api/documents/post_document/ endpoint. A look at the official API documentation before the first test run saves you the usual troubleshooting via a 415 error.

Can I also change existing tags in Paperless-ngx with n8n?

Yes, via the REST API you can read documents including their tag assignment and update them with a PUT or PATCH call, provided the token used has the necessary permissions. This is useful, for example, to mark receipts as "booked" after the fact, once accounting has processed them.

Does the automation also work if Paperless-ngx and n8n are on different servers?

Yes, as long as both systems can reach each other over the network and the respective URLs are correctly set in the script and workflow. In this case, pay particular attention to HTTPS and token-based authentication instead of open authentication, since the connection then runs over the public network or a VPN.