Invoice RadarInvoice Radar
Export

Paperless-ngx

Automatically upload invoices to your self-hosted Paperless-ngx instance

Overview

The Paperless-ngx integration automatically uploads your collected invoices to your self-hosted Paperless-ngx document management system.

Requirements

  • A running Paperless-ngx instance (self-hosted)
  • Your instance URL (accessible from your device)
  • Your Paperless-ngx API token

Setup

Required permissions

You can use a dedicated Paperless-ngx user for Invoice Radar. Grant it only the Documents → Add permission (documents.add_document), either directly or through a group.

Invoice Radar does not require Documents → View, Change, or Delete, staff or superuser access, or permissions for tags, correspondents, or document types. Make sure the integration user does not inherit broader permissions through its groups.

The connection test sends an authenticated GET /api/ request to check the instance URL and API token without retrieving documents or uploading a test file. A successful test confirms connectivity and credentials; Paperless-ngx checks the Add permission when an invoice is uploaded to POST /api/documents/post_document/.

Getting your API token

  1. Log in to your Paperless-ngx instance as the user you want Invoice Radar to use
  2. Go to My Profile
  3. Find the API section
  4. Copy your API token

For detailed instructions, see the official Paperless-ngx API documentation.

Configuring in Invoice Radar

  1. Open Invoice Radar and go to Settings → Export
  2. Click Add destination and select Paperless-ngx
  3. Enter your configuration:
    • Instance URL - Your Paperless-ngx server address (e.g., https://paperless.example.com)
    • API Token - Your Paperless-ngx API token
  4. Choose a start date:
    • All invoices - Export everything in your collection
    • From specific date - Only export invoices after the selected date
  5. Click Test Connection to verify the instance URL and API token
  6. Enable the destination

How it works

When you export invoices to Paperless-ngx:

  • Each invoice is uploaded as a new document
  • The document title is set to: {Vendor Name} - {Invoice ID}
  • The invoice date is preserved as the document date
  • The PDF is uploaded and processed by Paperless-ngx's OCR

Paperless-ngx will then apply its matching rules, tags, and correspondent assignments based on your configuration.

Exporting invoices

Bulk export

Click Export Now in the Export settings to sync all unsynced invoices. Progress is shown in real-time.

Individual export

Open any invoice in the document details panel to see its export status and manually trigger an export.

Network requirements

Your Paperless-ngx instance must be accessible from the device running Invoice Radar:

  • Local network: Use your local IP or hostname
  • Remote access: Ensure your instance is accessible via a public URL or VPN
  • HTTPS recommended: Use TLS encryption for security

Troubleshooting

"Connection refused" error

  • Verify your instance URL is correct and accessible
  • Check that your Paperless-ngx server is running
  • Ensure no firewall is blocking the connection

"Unauthorized" error

  • Verify your API token is correct
  • Check that your token hasn't expired or been regenerated

"Insufficient permissions" or HTTP 403 during export

  • Grant the integration user Documents → Add (documents.add_document), directly or through a group
  • Document read permission is not required; see Required permissions

Documents not appearing in Paperless-ngx

  • Check the Paperless-ngx logs for processing errors
  • Verify the upload succeeded in Invoice Radar's export history
  • Documents may take time to process through OCR

SSL/TLS errors

  • Invoice Radar honors locally trusted certificates for both connection tests and uploads
  • For a private certificate authority, install its root CA certificate in the trusted root certificate store on the device running Invoice Radar; for a self-signed server certificate, trust that certificate instead
  • On Windows, use Trusted Root Certification Authorities for the user running Invoice Radar (or the local computer), then fully quit and restart Invoice Radar
  • The certificate must be valid for the hostname in your instance URL (for example, storage) and must not be expired; your server must also send any required intermediate certificates
  • Adding an exception in a browser alone does not configure system certificate trust
  • Consider using a valid SSL certificate (e.g., from Let's Encrypt)

See Chromium's certificate trust documentation for the supported Windows certificate stores.

Security

  • Your API token is encrypted and stored only on your device
  • Invoices are sent directly to your Paperless-ngx instance with no intermediary
  • All connections should use HTTPS/TLS encryption

Need help? Check the Automatic Export overview or our Security & Privacy guide.