Invoice Extraction Node.js SDK: Developer Guide

An invoice extraction Node.js SDK lets a JavaScript or TypeScript backend upload invoice PDFs and images, submit extraction instructions, poll for completion, and download structured results. The important point is that invoice extraction is an async document workflow, not plain PDF text parsing: the application has to manage files, job state, output formats, and failed pages before the data is safe to write downstream.

That is the gap a dedicated invoice extraction Node.js SDK fills. In Invoice Data Extraction, the official Node package handles the upload, submission, polling, and download path for simple jobs through client.extract(...), while still exposing staged methods when extraction belongs in a queue, worker, or serverless flow.

This is different from a generic invoice OCR Node.js SDK that only returns text, and it is different from a REST-only integration where every upload session and polling request has to be wired by hand. It is also a different decision from building a DIY vision LLM pipeline, where the development team owns file handling, prompts, structured outputs, retries, and validation behavior.

The runtime assumptions are modern but ordinary for a current Node service. Node.js 18 is a natural baseline because the Node.js v18 fetch documentation shows that v18 made the browser-compatible fetch API available without the experimental fetch flag. The SDK still matters because the hard part is not making HTTP requests; it is turning invoice files into reliable, inspectable extraction jobs with structured JSON, CSV, or Excel output.

Set up the official Node SDK

Install the official package with npm install @invoicedataextraction/sdk. The SDK is ESM-only, so a Node project should either use "type": "module" in package.json or place the integration in an .mjs file. The import shape is import InvoiceDataExtraction from "@invoicedataextraction/sdk", and TypeScript declarations are included with the package.

Authentication is handled when the client is constructed. The SDK expects an api_key, usually loaded from an environment variable rather than committed into application code. A base_url can be supplied for advanced cases, but the default points to https://api.invoicedataextraction.com/v1.

That setup gives a Node service access to the same extraction capability exposed through the Invoice Data Extraction REST API. The practical reason to use the SDK is that it wraps the moving parts behind an invoice extraction API and SDK: upload session creation, file-part upload to presigned URLs, upload completion, extraction submission, polling, and output URL retrieval.

If you specifically need to see the raw HTTP sequence, the REST invoice extraction API quickstart is the better starting point. For most Node.js and TypeScript backends, the SDK is the cleaner default because it keeps the invoice workflow in application-level methods instead of scattering upload and polling details through service code.

Use extract for the happy path

For a first integration, client.extract(...) is the method to understand. It runs the whole invoice workflow in one call: upload the source files, submit the extraction task, poll until the task reaches a terminal status, and optionally download the result files.

import InvoiceDataExtraction from "@invoicedataextraction/sdk";

const client = new InvoiceDataExtraction({
  api_key: process.env.INVOICE_DATA_EXTRACTION_API_KEY,
});

const result = await client.extract({
  files: ["./invoices/acme-001.pdf"],
  prompt: {
    general_prompt: "Extract invoice header fields and totals for AP review.",
    fields: [
      { name: "invoice_number", prompt: "The supplier invoice number" },
      { name: "invoice_date", prompt: "The invoice issue date" },
      { name: "total_amount", prompt: "The final amount due" },
    ],
  },
  output_structure: "per_invoice",
  download: {
    formats: ["json"],
    output_path: "./outputs",
  },
  polling: {
    interval_ms: 10000,
  },
});

if (result.status === "failed") {
  throw new Error(result.error?.message ?? "Invoice extraction failed");
}

if (result.pages?.failed_count) {
  console.warn("Pages need review", result.pages.failed);
}

The method accepts two local input styles. Use folder_path when the invoices are already in one local folder; the SDK uploads supported files from that folder, but it does not recurse through nested directories. Use files when the application already has an explicit array of local file paths. The supported file extensions are .pdf, .jpg, .jpeg, and .png. The documented limits are 150 MB for a PDF, 5 MB for a JPG, JPEG, or PNG image, 2 GB total batch size, and up to 6,000 files per session.

Prompting can be simple or structured. A string prompt works when the extraction instruction is readable as one plain-language request, such as asking for invoice number, vendor, date, subtotal, tax, total, and currency. An object prompt is better when the application needs a more controlled schema: it can include fields and general_prompt, with each field carrying a name and optional field-level prompt.

The output_structure option decides how invoice data is arranged. Use per_invoice when each source invoice should produce one record with document-level fields. Use per_line_item when line-level purchase data matters and each row should represent an invoice line. Use automatic when the extraction engine should choose the structure from the prompt and documents.

Other options are worth knowing before the integration hardens. task_name makes the job easier to identify later, exclude_columns can remove the "source_file" column, download controls which formats are written to disk, polling controls wait behavior, console_output controls SDK logging, and on_update lets the application receive lifecycle updates while the job runs.

This is where Invoice Data Extraction is more than a thin invoice to JSON Node.js API wrapper. The SDK accepts invoice PDFs and images, applies natural language or structured field instructions, and returns structured output that can be downloaded as XLSX, CSV, or JSON.

Check the result before writing invoice data downstream

Treat the SDK response as job evidence, not just extracted data. client.extract(...) returns the terminal polling response unchanged, which means the application should inspect the status and page-level fields before writing invoice data into a database, AP workflow, ERP import, or analytics table.

A task that ends with status: "failed" is returned in the response rather than thrown as an exception. SDK or API operational failures are different: those throw, with structured response data available on error.body. That distinction matters in job code because a failed extraction task and a failed HTTP operation usually need different retry and alerting behavior.

For completed jobs, check pages.successful_count and pages.failed_count before trusting the output. The detailed arrays, pages.successful and pages.failed, identify page outcomes; failed page entries include file_name and page. A job can produce usable output while still needing human or application-level review for failed pages, especially when a batch mixes clean invoices with scans, rotated pages, or damaged files.

The response can also include ai_uncertainty_notes. Those notes use topic, description, and suggested_prompt_additions to flag extraction caveats and prompt improvements. In practice, that is useful feedback for tightening field instructions before the same workflow runs against the next batch.

Once the SDK has returned structured output and failed pages have been checked, validation belongs in the application layer. A TypeScript backend can use the extraction result as input to a schema step such as TypeScript invoice extraction validation with Zod, where field types, required values, currency formats, and business rules can be enforced before persistence.

Move to staged methods when extraction belongs in a job system

The one-call method is useful when a backend can afford to start an extraction and wait for the terminal response in the same application path. A staged workflow is a better fit when the application needs durable job state, separate upload and extraction phases, custom retries, progress visibility, or orchestration outside a single request lifecycle.

The SDK exposes those stages directly. uploadFiles(...) uploads local files and returns an upload_session_id with file_ids. submitExtraction(...) submits the uploaded files and returns an extraction_id plus submission_state. waitForExtractionToFinish(...) polls until the extraction reaches completed or failed, while checkExtraction(...) performs a one-time status check. For output, downloadOutput(...) writes one format to disk, and getDownloadUrl(...) returns a fresh presigned URL.

Those methods map cleanly to background infrastructure. A web request can create or receive the source files, a worker can upload and submit them, a queue can store the extraction_id, and another worker can poll or check status later. That shape is usually a better match for a serverless invoice processing architecture than holding a user-facing request open while a document job runs.

Polling options give the application control over how noisy or patient that worker should be. The default polling interval is 10000 milliseconds, the minimum is 5000 milliseconds, and timeout_ms can be left unset or specified when the job has a maximum runtime budget. The on_update({ stage, level, message, progress, extraction_id }) callback gives the application lifecycle data for logs, dashboards, or job progress records.

Two secondary methods round out the operational surface. deleteExtraction(...) is available when an application needs to remove an extraction record, and getCreditsBalance() can check available credits before or after work is submitted. These are supporting methods, not replacements for the core upload, submit, poll, and download flow.

Download JSON, CSV, or Excel for the system that comes next

Invoice extraction does not end when the job reaches completed. The useful artifact is the output file the next system can consume. The Node SDK supports xlsx, csv, and json, so the format choice should follow the destination rather than the extraction step itself.

Use JSON when the result is going into application objects, an API response, a database ingestion step, or a validation layer. Use CSV when the destination expects a flat import file. Use XLSX when a finance team needs a workbook they can review, filter, and share without asking a developer to build an interface first.

In the one-call path, the download option accepts formats and output_path, so the SDK can write the requested output files after polling finishes. In a staged workflow, downloadOutput(...) accepts extraction_id, format, and file_path, which lets a worker decide exactly when and where a result file should be saved.

When the application needs to hand download responsibility to another service, getDownloadUrl(...) returns download_url, format, and expires_in_seconds. Those output URLs expire after 5 minutes; REST responses also expose output_expires_at. That short expiration window is useful for security, but it means a durable workflow should store the extraction ID and request a fresh URL when it is ready to fetch the file.

For some workflows, the output also needs a small amount of shaping. The exclude_columns option supports "source_file" when that column is not needed in the downstream file. Keep this kind of shaping close to the extraction call only when it is universal for the workflow; business-specific cleanup still belongs in the application after the result is downloaded and checked.

Choose the SDK, REST, or DIY path deliberately

Use the Node SDK when a JavaScript or TypeScript backend needs invoice extraction as application infrastructure, but the team does not want to hand-wire upload sessions, polling loops, download URL refreshes, and failed-page checks. That is the default path for most SaaS upload flows, finance automation workers, and internal AP tools.

Use the REST API directly when the team needs full protocol control, another runtime, a custom HTTP client layer, or a deployment environment where the Node package is not the right fit. The REST flow exposes the same underlying stages, but the application owns more of the orchestration.

Use a DIY extraction stack only when that ownership is the point. A team choosing DIY vision LLM invoice extraction in Node.js is also choosing to manage file parsing, image preparation, prompt behavior, model responses, retries, validation, output shaping, and failure reporting itself. That can be valid for research or specialized systems, but it is not the same implementation job as adopting an official SDK.

Invoice Data Extraction keeps the commercial model straightforward for API work: web and API usage share a single credit balance, and API usage does not require a separate API subscription. That matters when the same organization has finance users working in the web product and developers embedding extraction into backend systems.

For a production Node integration, start with client.extract(...), inspect pages.failed_count and pages.failed, validate the structured output before downstream writes, and move to staged methods when the application needs durable workflow control.