@invoicedataextraction/sdk

Official Node.js SDK for Invoice Data Extraction. Handles file upload, extraction submission, polling, and result download so you can go from local files to structured output in a few lines of code.

• Node.js 18 or later
• ESM only

Install

npm install @invoicedataextraction/sdk

This package is ESM only. Your project's package.json must include "type": "module" (or use .mjs file extensions). TypeScript declarations are included.

Quick Start

import InvoiceDataExtraction from "@invoicedataextraction/sdk";

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

const result = await client.extract({
  folder_path: "./invoices",
  prompt: "Extract invoice number and total",
  output_structure: "per_invoice",
  download: {
    formats: ["xlsx", "json"],
    output_path: "./output",
  },
  console_output: true, // remove to disable console logging
});

extract(...) uploads your files (pass a folder_path or a list of files), submits the extraction, polls until it finishes, and downloads the results. The returned result is the final polling response from the API. Check result.pages.failed_count to verify that all uploaded pages were processed successfully, and check result.review_needed.count for any extracted values that require human verification before relying on the extracted data.

Generate an API key from your dashboard. Every account includes 50 free pages per month. Additional credits can be purchase on a pay-as-you-go basis with no subscription needed.

Staged Workflow

If you need control over individual steps — for example, uploading files in one part of your system and extracting in another — use the lower-level methods:

const upload = await client.uploadFiles({
  files: ["./invoice1.pdf", "./invoice2.pdf"],
  console_output: true,
});

const submitted = await client.submitExtraction({
  upload_session_id: upload.upload_session_id,
  file_ids: upload.file_ids,
  prompt: "Extract invoice number and total",
  output_structure: "per_invoice",
});

const result = await client.waitForExtractionToFinish({
  extraction_id: submitted.extraction_id,
  console_output: true,
});

await client.downloadOutput({
  extraction_id: submitted.extraction_id,
  format: "xlsx",
  file_path: "./output/invoices.xlsx",
});

Listing past extractions

// One-page browse with filters
const page = await client.listExtractions({
  status: "completed",
  limit: 50,
});

// Auto-paginating iterator over every matching extraction
for await (const extraction of client.iterateExtractions({ status: "completed" })) {
  console.log(extraction.extraction_id, extraction.task_name);
}

// Full record (the original prompt, options, full pages, full failure error, etc.)
const { extraction } = await client.getExtraction({ extraction_id: "..." });

Team admins can pass scope: "team" on listing methods to browse team-visible extractions, or scope: "own" to force own-only listing.

Error Handling

SDK methods reject with a normal JavaScript Error. The structured error body is on error.body:

try {
  await client.extract({ /* ... */ });
} catch (error) {
  console.log(error.body.error.code);    // e.g. "INVALID_INPUT"
  console.log(error.body.error.message); // Human-readable message
  console.log(error.body.error.retryable);
}

When an extraction task itself reaches a terminal state, extract(...) returns that response rather than throwing — check result.status for "completed", "failed", or "cancelled" for tasks cancelled from the web app.

Documentation

• Node SDK docs — full method reference, parameters, return shapes, and examples
• REST API docs — endpoint-level documentation for direct HTTP integration
• Dashboard — manage API keys and view extraction results

License

MIT