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.

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 Run All 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. Point Paperless-ngx's 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 pointing the panel at the new place with the change link at the top, which it takes as it is, nothing is copied.
• 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.

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 Run All 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, the Verify button (under more) checks every PDF the index knows about and reports the ones missing, and deleting a document's entry from progress.json makes the next run fetch it fresh. 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

PaperPull runs on your Windows or Mac machine, because it needs a real browser to sign in with. 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. 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 Status tab shows which archives are due.
2. For each one, pick it, click Run All. If the sign-in has expired, click Login first and sign in.
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