Invoice Extraction API: Developer Quickstart Guide

An invoice extraction API accepts invoice PDFs and images through REST endpoints and returns structured data in JSON, CSV, or Excel. Unlike a traditional invoice OCR API that stops at converting images to raw text, a modern document extraction API like the Invoice Data Extraction API uses LLM-powered intelligence to understand field relationships on the page. It distinguishes invoice dates from due dates, matches line items to totals across multi-page documents, and returns structured output directly, without custom parsing rules or per-vendor templates. You describe what you need in a natural language prompt, and the API handles layout detection, field matching, and data structuring.

According to Postman's 2025 State of the API report, 82% of organizations have adopted an API-first approach, up from 74% in 2024. Invoice Data Extraction's REST API fits this pattern: it exposes the same extraction engine available through the web platform, with natural language prompts, batch processing of up to 6,000 files per session, and output in XLSX, CSV, or JSON. This guide walks through the complete REST lifecycle using curl and HTTP examples: authenticate, upload documents, submit extraction tasks, poll for results, and download structured output. If you want to orchestrate the same flow in no-code tools, our guide to invoice extraction workflows in Zapier, Make, and n8n covers mapping, retries, and review routing. It then covers output formats, batch processing, error handling and rate limits, and when to reach for the Python or Node.js SDK instead.

If you are still evaluating whether an API is the right deployment model for your use case, it is worth comparing API vs SaaS vs ERP deployment models for invoice capture before diving into implementation details.

---

Authentication and Your First API Call

Every request to the Invoice Data Extraction API authenticates via a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate your API key from the dashboard under API settings. There is no separate API subscription, no approval process, and no waiting period. Your key shares the same credit balance as the web platform: 50 free pages per month, with pay-as-you-go credit bundles available when you need more. One credit equals one successfully processed page (a PDF page or an image). Failed pages are not charged.

Base URL

All endpoints in this guide are relative to:

https://api.invoicedataextraction.com/v1

Verify Your Setup

Before building anything, confirm your API key works by checking your credit balance. This is the simplest GET request in the invoice extraction API and requires no request body:

curl -X GET https://api.invoicedataextraction.com/v1/credits/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response looks like this:

{
  "success": true,
  "credits_balance": 50,
  "credits_reserved": 0
}

credits_balance is your total available credits. credits_reserved reflects credits held against in-progress extraction tasks that have not yet completed.

If you get a response back with your balance, authentication is working and you can move on to uploading documents.

Authentication Errors

If the request fails, the error code tells you exactly what went wrong:

• UNAUTHENTICATED (HTTP 401): The API key is missing or invalid. Double-check that you included the Authorization: Bearer prefix and that the key matches what the dashboard shows.
• API_KEY_EXPIRED or API_KEY_REVOKED: The key is no longer valid. Generate a new one from the dashboard and swap it into your configuration.

All error responses follow a consistent structure with a success field set to false and an error object containing the code and a human-readable message, so your error handling logic can be uniform across the entire API surface.

The Complete REST Workflow: Upload to Structured Output

With a valid API key in hand, you can process your first invoice. The extraction lifecycle is a six-step sequence: create a session, upload the file, confirm the upload, submit the extraction task, poll for completion, and download the result. Every step below uses a running example of processing a single PDF named invoice-001.pdf (roughly 500 KB).

Step 1: Create an upload session

Start by telling the API which files you plan to upload. Each session needs a developer-chosen ID and an array of file metadata.

curl -X POST https://api.invoicedataextraction.com/v1/uploads/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_session_id": "session-2026-03-27",
    "files": [
      {
        "file_id": "inv-001",
        "file_name": "invoice-001.pdf",
        "file_size_bytes": 524288
      }
    ]
  }'

The response includes a part_size value (8,388,608 bytes, or 8 MB). Since most invoices are well under 8 MB, you will typically need only one upload part per file.

Step 2: Get presigned upload URLs

Next, request a presigned URL for each part of each file. Calculate the number of parts as ceil(file_size_bytes / part_size). For a 500 KB file, that is 1.

curl -X POST https://api.invoicedataextraction.com/v1/uploads/sessions/session-2026-03-27/parts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "inv-001",
    "part_numbers": [1]
  }'

The response returns presigned S3 URLs. These expire after 15 minutes, so proceed to the upload promptly.

Step 3: Upload file bytes and complete the upload

PUT the raw file bytes directly to the presigned URL. Capture the ETag header from the response (it will be a quoted string like "a1b2c3d4...").

curl -X PUT "PRESIGNED_URL_FROM_STEP_2" \
  --upload-file invoice-001.pdf

Then confirm the upload by posting the part number and ETag back to the API:

curl -X POST https://api.invoicedataextraction.com/v1/uploads/sessions/session-2026-03-27/complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "inv-001",
    "parts": [
      {
        "part_number": 1,
        "e_tag": "\"a1b2c3d4e5f6...\""
      }
    ]
  }'

Step 4: Submit the extraction task

This is where you tell the API what data to pull from your invoices. The prompt field accepts a plain-text natural language instruction (up to 2,500 characters) describing what to extract. The output_structure field controls how results are organized: per_invoice (one row per document), per_line_item (one row per line item), or automatic (let the engine decide based on your prompt).

curl -X POST https://api.invoicedataextraction.com/v1/extractions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "submission_id": "extract-001",
    "upload_session_id": "session-2026-03-27",
    "file_ids": ["inv-001"],
    "prompt": "Extract invoice number, invoice date, vendor name, net amount, tax, total amount",
    "output_structure": "per_invoice"
  }'

The API returns HTTP 202 with an extraction_id and a submission_state of "received". Behind the scenes, the extraction is powered by a multi-model AI engine that understands document context, field relationships, and layout variations rather than relying on rigid template matching. For a deeper look at how LLM-powered invoice extraction works under the hood, see our dedicated technical article.

Step 5: Poll for results

Use the extraction ID to check progress. Poll no more frequently than every 5 seconds.

curl https://api.invoicedataextraction.com/v1/extractions/EXTRACTION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

While the task is running, the response includes a progress value from 0 to 100 and a status of "processing". Once complete, the status changes to "completed" and the response body expands to include:

• credits_deducted indicating how many page credits were consumed
• pages.successful_count and pages.failed_count for a quick pass/fail summary
• ai_uncertainty_notes where the AI flags assumptions it made about ambiguous fields
• output containing xlsx_url, csv_url, and json_url for direct download (these URLs expire after 5 minutes)

If the status is "failed", the response includes an error code and message explaining what went wrong.

Step 6: Download the output

You can either use the URLs returned in the polling response or request a fresh download link for a specific format:

curl https://api.invoicedataextraction.com/v1/extractions/EXTRACTION_ID/output?format=json \
  -H "Authorization: Bearer YOUR_API_KEY"

This returns a download_url with a 300-second expiry. Fetch that URL to retrieve your structured JSON, CSV, or Excel file containing the extracted invoice data.

---

Output Formats and Batch Processing

You choose the output format at download time, not when you submit the task, so you can pull JSON for your application database and hand the same extraction to finance as XLSX without reprocessing.

JSON returns an array of objects, one per row. This is the natural fit for API pipelines and programmatic consumption where the data feeds directly into application logic or a database insert — our guide to converting invoices to JSON walks through schema design, output examples, and format trade-offs in detail.

CSV produces a flat file suitable for data imports, ERP ingestion, and accounting software that expects delimited input. If your workflow centers on extracting invoice data directly to CSV, the dedicated guide covers format-specific considerations in more depth.

XLSX delivers natively typed values. Numbers arrive as numbers, dates as dates, so formulas and pivot tables work immediately without cleanup. This is the format to use when the output goes to a person rather than a system.

To download results in a specific format, request a fresh URL from the output endpoint:

GET /v1/extractions/{extraction_id}/output?format=json

The response returns a download_url with a five-minute expiration window. Call it once for JSON, again for CSV, again for XLSX if you need all three.

Scaling to Batch Processing

The same upload session workflow from a single invoice scales directly to production volumes. Instead of uploading one file, you add more files to the session before submitting the extraction. All files in a batch share the same prompt and output structure.

The limits are generous enough for most production scenarios: 6,000 files per session, 2 GB total upload size, with individual PDFs up to 150 MB and images (JPG, PNG) up to 5 MB each.

When you poll a batch extraction, the response tracks granular progress. The pages.successful_count and pages.failed_count fields give you a running total, while pages.successful and pages.failed arrays provide per-page detail including the source file name and page number. Credits are only deducted for successfully processed pages, so failed pages in a batch do not cost anything.

Structured Prompts for Repeatable Pipelines

For production systems, hardcoding a free-text prompt string works but is fragile. The prompt field also accepts a structured object that codifies your extraction rules into a schema:

• A fields array where each entry has a name (2 to 50 characters, required) and an optional prompt (3 to 600 characters) describing extraction rules for that field.
• A general_prompt (up to 1,500 characters) for cross-cutting instructions like date formatting or page filtering rules.

A payment processing pipeline might define fields for invoice number, vendor name, invoice date, due date, purchase order number, currency, and total amount, with a general prompt like: "Format all dates as YYYY-MM-DD. For credit notes, prefix amounts with a negative sign. Skip any pages that are remittance advice or cover letters."

The same schema-driven approach is useful when your extraction service handles utilities instead of standard invoices; this guide to a utility bill OCR API with JSON outputs shows how developers model account numbers, service periods, charges, and meter readings for downstream systems.

This structured approach is more maintainable than a single prompt string when you have multiple fields with individual extraction logic. It also makes it straightforward to version-control your extraction configuration alongside your application code.

Controlling Output Structure

The output_structure parameter determines how rows map to your source documents:

• per_invoice produces one row per document. Use this when you need invoice-level data like invoice number, date, vendor, and total.
• per_line_item produces one row per line item within each invoice. This is the right choice for spend analysis, procurement workflows, or any case where you need granular item-level detail.
• automatic lets the AI decide based on your prompt content.

Set this explicitly in production. Relying on automatic is fine during prototyping, but a pipeline that switches output structure based on AI interpretation will cause downstream schema mismatches.

If you need to apply the same output-structure choices to purchase orders, this guide to purchase order OCR API implementation patterns shows how to shape PO headers and line items for downstream validation and matching.

Error Handling and Rate Limits

Oversized files, expired keys, rate limit spikes during month-end processing. Your retry logic determines whether your invoice parsing API pipeline recovers gracefully or drops invoices.

The Error Response Contract

All error responses follow a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for submit endpoint",
    "retryable": true,
    "details": {
      "retry_after": 2
    }
  }
}

The retryable boolean is the field your code should branch on. When it returns true, implement exponential backoff and retry. When it returns false, surface the error to your application layer because no amount of retrying will fix it.

Retryable Errors: Build Backoff Logic

These error codes signal transient failures. Retry with exponential backoff:

• RATE_LIMITED — Always respect the Retry-After header before your next attempt.
• UPLOAD_COMPLETE_FAILED — The upload confirmation step failed server-side. Retry the completion call.
• CONCURRENT_TASK_LIMIT — Too many extractions running simultaneously. Back off and resubmit.
• SUBMISSION_STALLED — The extraction task stalled mid-processing. Resubmit safely.
• INTERNAL_ERROR — Server-side failure. Retry with increasing delays.

A basic retry pattern: start at 1 second, double on each attempt, cap at 32 seconds, and stop after 5 retries. For RATE_LIMITED specifically, always use the Retry-After value instead of your own backoff calculation.

Non-Retryable Errors: Surface Immediately

These errors require human intervention or code changes. Do not retry them.

Credential failures: UNAUTHENTICATED, API_KEY_EXPIRED, and API_KEY_REVOKED all mean your authentication is invalid. Rotate or renew the key.

Account issues: INSUFFICIENT_CREDITS means no credits remain on the account. Processing stops until credits are added.

File problems: FILE_TOO_LARGE triggers when a PDF exceeds 150 MB or an image exceeds 5 MB. ENCRYPTED_FILE means the PDF is password-protected and cannot be processed. DUPLICATE_FILE_NAME and DUPLICATE_FILE_ID indicate naming conflicts that need resolution before reuploading.

Extraction failures: PROMPT_REJECTED and PROMPT_UNCLEAR flag issues with custom extraction prompts. NO_PAGES_FOUND means the document contained no extractable pages (blank scans, image-only PDFs without OCR content).

Partial Failures Within Completed Extractions

A completed extraction can still contain page-level failures. The pages.failed array lists each page that could not be processed, along with the reason. Credits are not charged for failed pages, so you only pay for what actually extracted.

Check the ai_uncertainty_notes field on completed results. It flags fields where the model had low confidence in the extracted value. For financial data, low-confidence fields on amounts or tax calculations should trigger a human review queue rather than flowing directly into your accounting system.

Rate Limits by Endpoint

Each API key enforces per-minute limits across endpoints:

Endpoint	Requests per minute
Upload	600
Submit	30
Poll	120
Download	30
Delete	30
Balance	60

The submit endpoint at 30 requests per minute is the production bottleneck. If your batch pipeline processes hundreds of invoices, you need to throttle submission calls or queue them. The upload limit (600/min) is generous enough that you can pre-upload files well ahead of submission.

Idempotency and Safe Retries

Duplicate session IDs and submission IDs return the existing resource rather than creating a new one. This means retries are safe by default. If your submit call times out and you are unsure whether it succeeded, resubmit with the same ID. You will either get the in-progress task or the completed result, never a duplicate charge.

---

When to Use the Python or Node.js SDK Instead

The REST workflow covered above gives you full control over every HTTP request, but it also means you are managing six discrete steps: authentication, file upload, task submission, polling, status checking, and output download. The official Python and Node.js SDKs collapse that entire sequence into a single function call.

One Call Instead of Six Steps

Both SDKs expose an extract() method that handles upload, submission, polling, and download internally. Here is the full integration in Python:

from invoicedataextraction import InvoiceDataExtraction
import os

client = InvoiceDataExtraction(api_key=os.environ.get("INVOICE_DATA_EXTRACTION_API_KEY"))

result = client.extract(
    folder_path="./invoices",
    prompt="Extract invoice number, invoice date, vendor name, net amount, tax, total amount",
    output_structure="per_invoice",
    download={"formats": ["xlsx", "json"], "output_path": "./output"},
)

Install with pip install invoicedataextraction-sdk (Python 3.9+).

And the equivalent in Node.js:

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, invoice date, vendor name, net amount, tax, total amount",
  output_structure: "per_invoice",
  download: { formats: ["xlsx", "json"], output_path: "./output" },
});

Install with npm install @invoicedataextraction/sdk (Node 18+, ESM only). TypeScript declarations are included out of the box.

Both examples do the same thing the six-step REST workflow does: upload every file in the folder, submit the extraction task, poll until completion, and download the results as XLSX and JSON. The SDK handles all of it. If you want to go a step further and expose invoice extraction as your own FastAPI endpoint, the Python SDK slots in behind a route handler with Pydantic models, file uploads, and async batch support already covered.

Error Handling

In Python, import SdkError and ApiResponseError from invoicedataextraction.errors and catch both:

from invoicedataextraction.errors import SdkError, ApiResponseError

try:
    result = client.extract(...)
except (SdkError, ApiResponseError) as error:
    print(error.body["error"]["code"])
    print(error.body["error"]["message"])

In Node.js, use a standard try/catch block and access the error details through error.body.error:

try {
  const result = await client.extract({ ... });
} catch (error) {
  const { code, message, retryable } = error?.body?.error || {};
  console.log(code, message);
}

Error responses include a machine-readable code, a message, and a retryable boolean. Retries for RATE_LIMITED and transient INTERNAL_ERROR responses are handled automatically, so you only need to catch non-retryable failures yourself.

Staged Methods for Fine-Grained Control

If you need visibility into each phase of the workflow (for example, to show upload progress in a UI, or to separate file ingestion from extraction submission), both SDKs expose individual methods that map to the REST steps:

• upload_files / uploadFiles uploads documents and returns a session ID and file IDs.
• submit_extraction / submitExtraction submits the extraction task against uploaded files.
• wait_for_extraction_to_finish / waitForExtractionToFinish polls until the task reaches a terminal state.
• download_output / downloadOutput saves a single output format to disk.

You can also pass an on_update callback to any of these methods (or to extract() itself) to receive real-time progress events with stage, message, and numeric progress fields. Enable console_output for built-in logging during development.

REST vs. SDK: Choosing the Right Approach

Use the REST API when:

• Your application is written in a language other than Python or Node.js
• You need precise control over HTTP headers, retries, or request timing
• You already have an HTTP client framework that handles authentication and polling

If that unsupported-SDK path applies to your team, this PHP invoice extraction workflow guide shows how to handle upload sessions, polling, and structured output over raw REST. Teams building on the JVM can follow the same pattern with this Java invoice extraction REST integration guide, which shows how to wrap the staged workflow in a reusable client. If you are packaging the same workflow in a compiled service, this Go invoice extraction REST client guide shows how to manage uploads, safe polling, and output downloads in Go. Use an SDK when:

• You are building in Python or Node.js and want the workflow handled in a few lines of code
• You are running batch processing and want automatic retry for rate limits and transient errors
• You want built-in progress callbacks and structured error handling without writing polling logic

The SDKs are thin wrappers around the same REST endpoints. The difference is how much plumbing you want to write yourself. There is also a third integration path worth considering: if your workflow involves AI assistants that need to pull invoice data on demand, you can wrap the extraction API as an MCP server so that any Model Context Protocol-compatible client can call it as a tool without custom glue code. For teams designing fully autonomous AI agent workflows for invoice processing, the REST API and SDKs both serve as the extraction backbone that agents call during their decision loops.

If you are implementing against the API from Microsoft tooling, this walkthrough of invoice extraction from C# and .NET over REST shows how to handle uploads, polling, and typed result mapping cleanly.