Tutorial

How to collect financial statements for Paperless-ngx.

Paperless-ngx organizes your documents. PaperPull collects the ones still sitting inside your online accounts. Together they turn "I should really save those statements" into a folder that fills itself.

Paperless on a NAS or home server? PaperPull Server runs right beside it in Docker and copies each run's new documents into the consume folder by itself, with no shared folder to set up. Its setup is SERVER.md. The steps below are for the desktop app.

What each one does

Paperless-ngx is a document management system. You give it PDFs, it OCRs them, tags them, files them and makes them searchable. It is very good at that, and it has no idea how to get a statement out of Chase.

PaperPull is the other half. It signs in beside you to the sites that hold your statements and receipts, downloads every one the site offers, and writes ordinary PDFs into ordinary folders, named by date, provider, account and kind. It has no idea how to tag or search, and does not need to.

There is no special integration between them, and none is needed. PaperPull writes files, Paperless reads files. That is the whole design, and it is why it keeps working when either side updates.

1. Install PaperPull and collect a first provider

Follow the getting-started guide through Get new documents for one provider. Come back here once there is a folder of PDFs on disk. It usually takes fifteen minutes, most of it the bank's website being slow.

2. Decide where the PDFs live

PaperPull's downloads folder is the one you chose on its first screen. Under it is a folder per provider, and under that the PDFs by kind, with an index CSV and a small progress.json beside them. The progress.json file is PaperPull's memory of what it has already saved. Everything else is yours to move.

You have two sensible layouts.

• PaperPull writes, Paperless watches. The simplest way is to give Paperless-ngx's consume directory as the documents folder in PaperPull's Settings. When a run ends, only the documents it saved and checked move there, each provider and person in a folder of their own, while browser profiles and records stay in the PaperPull folder. Or point the consume directory at PaperPull's downloads folder, or at one provider's folder inside it. Paperless picks up each new PDF as it lands. This is the least work per month.
• PaperPull writes here, you copy there. Keep PaperPull's folder as your own long-term archive, and copy or move new PDFs into Paperless's consume directory when you want them indexed. This keeps a plain-file copy outside Paperless's database, which some people prefer.

Paperless-ngx's consume directory deletes each file after it imports it. That is how it works, and it is fine for PaperPull, because PaperPull does not need the PDF to remember it saved it. What you lose is a plain copy outside Paperless. If you want one, use the second layout, or set PaperPull's folder to be Paperless's consume directory only for providers you do not need a second copy of.

3. Point Paperless at the folder

In Paperless-ngx, the consume directory is PAPERLESS_CONSUMPTION_DIR in its configuration, or the consume volume in the usual Docker setup. Paperless needs to see the folder, which means one of:

• Paperless runs on the same computer as PaperPull, and its consume directory is set to, or bind-mounted from, PaperPull's downloads folder.
• Paperless runs on a server or NAS, and PaperPull's downloads folder is a network share that Paperless's consume directory points at. Set PaperPull's folder to the mapped drive or mounted share on its first screen. Moving it later means moving the provider folders there and choosing the new place in the panel's Settings, under Your PaperPull folder. The panel takes the folder as it is, and nothing is copied. Or keep PaperPull's folder on this computer and give the share as the documents folder in Settings, so only documents travel.
• Paperless runs elsewhere and you copy files across by hand, or with a scheduled copy, from PaperPull's folder to the consume directory.

Two Paperless settings matter for a folder PaperPull is writing into. PAPERLESS_CONSUMER_RECURSIVE=true, so Paperless looks inside the per-provider and per-kind subfolders, and PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true if you want the folder names (Chase Statements, Statements) to become tags, which is a cheap way to get a tag per provider.

Do not point the consume directory at the whole PaperPull folder if a provider's browser profile lives in it. On a packaged install the profile is a folder called browser-profile beside that provider's PDFs. Paperless only consumes document types it knows, so it will ignore the profile's files, but the cleanest arrangement is to consume the per-kind folders (Statements, Online) rather than the provider folder, which also keeps progress.json and the CSVs out of Paperless's way. A documents folder set in Settings avoids all of this, since browser profiles and records never move into it.

4. Repeat runs and duplicates

PaperPull remembers each document by what it is, its provider, account, date and kind, not by whether the file is still there. So after Paperless consumes and deletes a PDF, the next Get new documents still skips it. You will not get the same statement twice from PaperPull's side.

On Paperless's side, a file consumed twice is a duplicate, and Paperless refuses duplicates by checksum unless PAPERLESS_CONSUMER_DELETE_DUPLICATES is set. In the "PaperPull writes, Paperless watches" layout this does not come up, since each file is written once. In the copy-by-hand layout, copying a folder a second time is safe, Paperless rejects the repeats.

If you ever need PaperPull to fetch something again, Restore deleted files, in a provider's More menu, fetches again the PDFs you deleted, for a year or the dates you choose. Check saved files, in the same menu, checks every PDF already saved and downloads nothing. Both are rare.

5. Naming, and why Paperless likes it

Every PaperPull file is named 2026-08-31 Chase Sapphire Monthly Statement.pdf. Paperless reads the date at the front as the document date when PAPERLESS_FILENAME_DATE_ORDER=YMD is set, and the rest of the name becomes the title, so a search for "Sapphire" or "Monthly Statement" finds it before OCR has even run. A matching rule on "Chase" assigns a correspondent, and the folder-as-tag setting above gives the document type.

6. A NAS or a shared folder

The desktop app runs on your Windows or Mac machine, and its downloads folder can be anywhere that machine can write, including a mapped network drive or a mounted share on the NAS that runs Paperless. Or run PaperPull Server on the NAS itself, beside Paperless, and skip the share. With a share, two things to know.

• Keep the browser profile folders local. PaperPull puts each provider's profile beside that provider's downloads by default, and a profile on a network share is slow and occasionally locks. If your downloads folder is a share, set profile_dir in each provider's config.json to a local path, or keep the downloads folder local and copy PDFs to the share instead.
• progress.json lives in the provider folder and is rewritten after every document. On a share that is fine, just do not run the same provider from two machines against one folder.

7. The monthly routine

1. Open PaperPull. The Accounts page shows which accounts may have something new.
2. Click Get new for all, which runs each of them, one by one. If a sign-in has expired, the round waits at that account. Click Open sign-in window, sign in, and try it again.
3. New PDFs land in the folder. Paperless consumes them, or you copy them across.

That is the whole integration. Nothing to configure between the two, nothing that breaks when either updates, and a plain folder of dated PDFs in the middle that is yours whatever happens to either program.

Download PaperPull, free See which providers it collects from