@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.

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 fails (e.g. insufficient credits), extract(...) returns the failed response rather than throwing — check result.status for "completed" or "failed".

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