Folder Watcher

Updated 2026-09-07

Overview#

The Folder Watcher is a single script, not an add-in. Drop invoices in a folder, run it, and every PDF or image is extracted through the v3.1 API and written to an Excel workbook. Processed files move to done, failures move to failed, so nothing is lost or sent twice.

It suits a desk that receives invoices as files, a scanner that drops into a network share, or a scheduled job on a server. Nothing is installed beyond the script itself, and it calls the same API as every other integration, so accuracy, credit cost, and document limits are identical.

Two equivalent versions are published; pick the one that fits the machine:

Variant	File	Best for
PowerShell	`folder-watcher.ps1`	Any Windows machine, no install
Python	`folder_watcher.py`	Windows, macOS, or Linux with Python 3.9+, or building a self-contained `.exe`

Source: folder-watcher in the public examples repository, MIT licensed. A prebuilt executable is not published yet; the README shows how to build one.

Before you start#

An API key from the client portal → Settings
The document types your key permits — check on the Test API page
Documents as PDF, JPG, PNG, or WEBP, up to 10 MB
PowerShell 5.1 or later on Windows, or Python 3.9 or later on any platform

Tip

Give the watcher its own API key. Usage stays attributable per tool, and you can revoke it without disrupting your other integrations.

Setup#

1. Download the script#

Open the folder-watcher folder on GitHub and save the variant you want to a folder of your choice, for example C:\docxtract\. You can also clone the whole examples repository and copy the folder out.

The watcher creates its working folders next to the script on first run:

Folder	Purpose
`invoices`	Drop files here
`done`	Processed files, moved here after their data is written
`failed`	Files that errored, so you can inspect and retry
`output`	The Excel workbook or workbooks

2. Provide your API key#

The key is looked up in this order: a command-line flag, the config file, the DOCXTRACT_API_KEY environment variable, then an interactive prompt. On a first interactive run with no key the watcher asks once and saves it, so later runs and scheduled runs never prompt.

PowerShell, set it once for your Windows user:

[Environment]::SetEnvironmentVariable("DOCXTRACT_API_KEY", "your_api_key_here", "User")

Python, either set the same environment variable or let the first run write it into config.ini next to the script.

3. Run it#

PowerShell. If scripts are blocked, allow local scripts once with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. The first run installs the ImportExcel module for your user.

.\folder-watcher.ps1

Python.

pip install requests openpyxl
python folder_watcher.py

Both produce output\invoices.xlsx with an Invoices sheet, one row per document, and a LineItems sheet, one row per line item, linked by source_file. Re-running appends.

Screenshot pending

Terminal showing three invoices processed and moved to done, beside the Invoices sheet in Excel

Options#

Both variants share the same settings. PowerShell takes them as parameters; Python reads config.ini and accepts the same names as --flags.

Setting	Default	Meaning
`excel_mode`	`single`	`single` appends to one `invoices.xlsx`; `separate` writes one workbook per document
`document_type`	(blank)	Blank means the API default, `invoice`. Set it to any type on your key
`model`	(blank)	Blank means the API default. Set only if support has given you a model name
`in_folder`, `done_folder`, `failed_folder`, `out_folder`	as above	Relative paths resolve against the script's folder
`api_url`	`https://api.docxtract.io/v3.1/documents`	Leave as is

One workbook per document:

.\folder-watcher.ps1 -ExcelMode separate
python folder_watcher.py --excel-mode separate

A different document type:

.\folder-watcher.ps1 -DocumentType purchase_order
python folder_watcher.py --document-type purchase_order

The Excel layout is built for invoice-shaped results with a line_items array. Other types still produce the flattened first sheet.

Run on a schedule#

Windows Task Scheduler, every 15 minutes:

schtasks /Create /TN "DocXtract Folder Watcher" /SC MINUTE /MO 15 `
    /TR "powershell -NoProfile -ExecutionPolicy Bypass -File C:\docxtract\folder-watcher.ps1"

cron on macOS or Linux:

*/15 * * * * cd /opt/docxtract && python3 folder_watcher.py >> watcher.log 2>&1

Scheduled runs never prompt for a key. Save it first, or they exit with an error.

What to expect#

Credits are per page. A 10-page document costs 10 credits.
Rate limits are per key — 10 requests per minute by default. The watcher is sequential, so a large backlog processes at roughly that pace. Anything throttled lands in failed; move those files back to invoices for the next run.
PDFs over 3 pages are split and processed in parts, so they take noticeably longer.
The key is stored in plain text on the machine, in config.ini or a per-user environment variable. That is the same model as Git or cloud CLI credentials. Use a dedicated key, do not commit config.ini, and rotate the key if the machine is shared or retired.

Troubleshooting#

Symptom	Cause
Exits at once asking for a key	No key found in flag, config, or environment; run it once interactively to save one
Authentication fails on every file	Key is revoked, expired, or not a DocXtract `sk_` key
`400 unknown_model`	The document type is not assigned to this key — check the portal
Columns look wrong for the documents	Wrong document type; it defaults to `invoice`
Files pile up in `failed` during a large batch	Rate limit — 10 requests/minute per key; move them back and rerun
`running scripts is disabled` (PowerShell)	Execution policy; run the `Set-ExecutionPolicy` line above once
`ModuleNotFoundError: requests` (Python)	Run `pip install requests openpyxl` in the same Python you launch with
Stops working suddenly, mid-month	Credit cap reached; see quotas

Support#

support@docxtract.io — include the document type and roughly when the failure happened. Never send your API key. For bugs in the script itself, open an issue on the examples repository.

Something wrong or missing on this page? Tell us.