Description

n8n-nodes-refractr

This is an n8n community node for Refractr, a document extraction API. Give it an invoice, delivery note, bill of lading or any other document, as a file, scan or text, plus the fields you want, and it returns typed values with a confidence score per field. A field that isn’t in the document comes back as null.

The node sends results it’s confident about to one output and doubtful ones to a Needs Review output, so only those go to a person.

It also prepares files before upload, in n8n and at no cost: it takes a binary field, a URL or a base64 string, sends only the PDF pages you pick, shrinks large photos and scans, and sends text and HTML files as text.

Why not the Information Extractor?

We ran the same 11 public test invoices (7 fields each) through n8n’s Information Extractor and through this node:

| | Refractr node | Information Extractor + gpt-5-mini | Information Extractor + gpt-4o-mini |
|—|—|—|—|
| Fields right | 93% | 93% | 80% |
| Invoices fully right | 8 of 11 | 7 of 11 | 3 of 11 |
| Time per document | 0.5–1.6 s | 4–7 s | 1.3–2 s |
| Scanned PDF (no text layer) | Read with OCR | Workflow stops | Workflow stops |
| Confidence per field | Yes | No | No |
| Routes doubtful results to review | Built in | Build it yourself | Build it yourself |
| Needs an LLM credential and a prompt | No | Yes | Yes |

The Information Extractor used its default setup (fields from attribute descriptions) on n8n Cloud 2.42.6, 12 October 2026; Refractr was measured on 26 October 2026. Fields right counts exact values in the expected format, such as YYYY-MM-DD dates and numeric amounts.

n8n is a fair-code licensed workflow automation platform.

Installation · Operations · Credentials · Usage · Compatibility · Resources

Installation

Follow the installation guide in the n8n community nodes documentation, and install n8n-nodes-refractr.

Operations

Extraction

• Extract: extract fields from a file (PDF, Word, OpenDocument, a scan or photo, or a text or HTML file), given as a binary field, a URL or a base64 string, or from text.
• Get Job: get the result of an extraction by its job ID.

Account

• Get Credit Balance: the current balance plus lifetime purchased and used totals.
• Get Usage: daily request and credit totals over the last N days.

Credentials

1. Sign up and confirm your email address. Keys only work after that.
2. Create an API key in your dashboard.
3. In n8n, create a Refractr API credential and paste the key. Leave Base URL as it is.

Every account gets 20 free extractions per day, or 100 per day if you allow your documents to be used for training.

Usage

Defining the fields

Add each field with a name and a type: String, Number, Integer, Boolean, Date, or a list of one of those. Descriptive names work best (invoicedate beats d1). Use dots to nest fields, such as vendor.name and vendor.vatnumber.

For lists of objects, such as invoice line items, set Schema Definition to Using JSON Template and write a Refractr template:

{
  "invoice_number": "str",
  "total_amount": "float",
  "line_items": [{ "description": "str", "amount": "float" }]
}

Dates always come back as YYYY-MM-DD, and amounts as bare numbers (1249.0, not "EUR 1,249.00").

Input

Set Input to where the document comes from:

• File: a binary field from an earlier node, such as Gmail, Google Drive or Read Files from Disk.
• URL: a link to the file, which n8n downloads.
• Base64 String: the file as base64, or as a data URL (data:application/pdf;base64,...).
• Text: plain text, such as an email body.

The file type is detected from the file’s content, so a missing or wrong MIME type doesn’t matter. Text and HTML files (.txt, .csv, .html and the like) are sent as text; HTML is turned into plain text first. A file downloaded from a URL or decoded from base64 is added to the output as binary field data, so a reviewer can open it.

PDF pages

Set Options > PDF Pages to send only some pages of a PDF, such as 1-3, 5, 2- (page 2 to the end) or 1, last. The other pages are removed in n8n before upload, so a long PDF uploads faster and fits within the page limit. Pages a PDF doesn’t have are skipped, so 1-3 also works on a two-page PDF. Images that only the removed pages use are left out too.

Encrypted PDFs that use object streams can’t be split; remove the option to send them whole.

Large images

Add Options > Shrink Large Images to shrink JPEG and PNG images over 2000 pixels on their longest side, such as phone photos and 300 DPI scans, to 2000 pixels before upload. Refractr reads images at that size anyway, so the result is the same and the upload is smaller: a 12-megapixel photo goes from about 2 MB to about 0.7 MB. Photos are turned upright according to their EXIF orientation. Smaller images and other formats are sent as they are.

Scans and photos (OCR)

With OCR set to Auto, images are read with OCR. Other files are read from their text layer first, and retried with OCR only when they have none, such as scanned PDFs. The first attempt on a scan fails without being charged, so you only pay for OCR (2 credits instead of 1) when it’s needed. Choose Always for PDFs that mix text and scanned pages.

Routing by confidence

With Route by Confidence on, the node has two outputs:

• Confident: every scored field is at or above the Confidence Threshold (default 0.9).
• Needs Review: at least one field scored below it, a field listed under Options > Fields That Must Have a Value is empty, or the extraction failed while On Error is set to continue.

The input file is passed through on both outputs, so a reviewer can open the document. A typical workflow sends the Confident output to your accounting system or a spreadsheet, and Needs Review to Slack, email or a review sheet with reviewReasons in the message.

Fields Refractr doesn’t score, such as judgment fields (sentiment, category, is_… flags) and text longer than eight words, are ignored when routing.

Output

With Simplify on, each item looks like this:

{
  "data": { "invoicenumber": "VV-26-0412", "total": 1756.92, "ponumber": null },
  "confidence": { "invoicenumber": 0.9612, "total": 0.71, "ponumber": 0.98 },
  "needsReview": true,
  "reviewReasons": ["total: confidence 0.71 is below 0.9"],
  "lowConfidenceFields": ["total"],
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "creditsCharged": 1
}

Turn Simplify off to get the full API response, including validation.warnings and metadata, with the same review fields added.

Large files

An extraction normally waits for its result, up to 30 seconds. For large scans, set Options > Mode to Submit and Poll. Files can be up to about 7 MB, PDFs up to 20 pages (10 with OCR); use PDF Pages and Shrink Large Images to stay within them. See limits.

Rate limits

The API allows 60 requests per minute per key. When it’s exceeded, the node waits as long as the API asks and retries.

As an AI agent tool

The node can be used as a tool by n8n’s AI Agent, for extracting fields from text.

Compatibility

Tested with n8n 2.43.5.

Development

Requires Node.js 24 (n8n’s dependencies don’t build on Node 25 yet).

npm install
npm run dev    # starts n8n on http://localhost:5678 with this node loaded
npm test       # builds, then runs the tests in test/ against a mocked API
npm run lint

npm run build compiles with n8n-node build and then bundles the node with esbuild, so the published package has no runtime dependencies. The bundle includes pako (zlib decompression) and jpeg-js (JPEG decoding and encoding); their licenses are in Refractr API documentation

• n8n community nodes documentation

Version history

See CHANGELOG.md.