# Invoice Extraction (`vivid_astronaut/invoice-extraction`) Actor

- **URL**: https://apify.com/vivid\_astronaut/invoice-extraction.md
- **Developed by:** [BRAINIALL Team](https://apify.com/vivid_astronaut) (community)
- **Categories:** AI, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 document parseds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Invoice & Receipt Data Extraction — by Brainiall

Turn page images of invoices, receipts and other business documents into **structured JSON candidates** for accounting workflows, expense operations, document review and data pipelines.

Give the Actor one or more public **PNG, JPG/JPEG or WebP image URLs**, choose the document type, and receive one dataset item per image. The structured extraction endpoint accepts an image of a page; it does not accept PDF files.

For a PDF, first render the page you want to extract as PNG, JPG or WebP. If you want the PDF's text rather than structured fields, use the `pdf-to-markdown` Actor instead.

> Extracted values are candidates, not audited facts. Review important financial, legal and operational data before using it in a system of record or making a decision.

### What it does

- **Batch page-image parsing** — process multiple public HTTP or HTTPS PNG, JPG/JPEG or WebP URLs in one run.
- **Multiple document types** — identify an image as `invoice`, `receipt`, `contract`, `bank_statement` or another type supported by the API.
- **Useful structured output** — access extracted candidates directly in top-level `fields`, with OCR/source text in top-level `text`; the complete API response remains in `extracted_data` for compatibility.
- **Confidence visibility** — promote an overall confidence value to the top level when the engine supplies one; `confidence_available` makes absence explicit.
- **Resilient runs** — briefly retry rate limits and temporary service failures. Invalid inputs and final failures become uncharged dataset error items instead of ending the whole batch.

Powered by the **Brainiall Document engine** ([api.brainiall.com](https://app.brainiall.com)) — a production document-intelligence service for operational workloads.

### Who it's for

- **Finance and accounts-payable teams** — create review queues from incoming invoice candidates.
- **Expense operations** — turn receipt files into structured candidates for reconciliation.
- **Developers and automation builders** — feed document results into databases, webhooks and internal tools without maintaining a parsing stack.
- **Document operations teams** — normalize batches of page images for human review.

### Why this Actor

The Actor accepts multiple image URLs, limits concurrency, retries short-lived service failures, preserves the full API response and reports bad inputs beside successful ones. A PDF or unsupported file becomes an uncharged dataset error item with next-step guidance; it does not crash the batch. You are charged only for delivered structured results.

### Input

```json
{
    "documentUrls": [
        { "url": "https://example.com/invoices/invoice-1042-page-1.png" },
        { "url": "https://example.com/invoices/invoice-1043.jpg" }
    ],
    "documentType": "invoice"
}
```

| Field | Description |
|-------|-------------|
| `documentUrls` | Public HTTP or HTTPS URLs pointing directly to PNG, JPG/JPEG or WebP page images. Each URL produces one dataset item. PDF is not accepted. |
| `documentType` | One supported type applied to the batch. Common examples are `invoice`, `receipt`, `contract` and `bank_statement`. |

Use separate runs when documents in a batch have different types.

### Output

One dataset item is written per input URL. The candidate field values below come from a real invoice extraction; the opaque request ID and raw text are abbreviated. The contents of `fields` vary by document type and image:

```json
{
    "success": true,
    "input_index": 0,
    "file_url": "https://example.com/invoices/invoice-1042-page-1.png",
    "document_type": "invoice",
    "image_format": "png",
    "request_id": "...",
    "fields": {
        "invoice_number": "2026-1042",
        "vendor_name": "Acme Industrial Ltda",
        "issue_date": "2026-08-09",
        "currency": "USD",
        "total": 1250.0,
        "line_items": []
    },
    "text": "...",
    "fields_are_candidates": true,
    "confidence": null,
    "confidence_available": false,
    "extracted_data": {
        "request_id": "...",
        "doc_type": "invoice",
        "fields": {
            "invoice_number": "2026-1042",
            "vendor_name": "Acme Industrial Ltda",
            "issue_date": "2026-08-09",
            "currency": "USD",
            "total": 1250.0,
            "line_items": []
        },
        "text": "..."
    }
}
```

`fields_are_candidates` is always `true`: extracted values are machine-produced candidates, not audited data. The raw extracted text remains available in `text`. If the engine reports an overall confidence value, it is also promoted to `confidence`; otherwise `confidence` is `null` and `confidence_available` is `false`.

Invalid inputs and documents that still fail after retries are returned as uncharged error items:

```json
{
    "success": false,
    "input_index": 1,
    "file_url": "not-a-url",
    "document_type": "invoice",
    "error": {
        "reason": "Document URL must be a valid public HTTP or HTTPS URL."
    }
}
```

A PDF receives a specific, actionable error item:

```json
{
    "success": false,
    "input_index": 0,
    "file_url": "https://example.com/invoice.pdf",
    "document_type": "invoice",
    "error": {
        "reason": "The structured document extractor accepts one page image (PNG, JPG/JPEG, or WebP), not a PDF. Convert the PDF page you want to extract to an image and submit that image URL. If you need the PDF text instead, use the pdf-to-markdown Actor."
    }
}
```

Export the dataset as JSON, CSV or Excel, or consume it through the Apify API.

### Pricing

You pay **per successfully parsed document** through the `document-parsed` event. Invalid inputs, final failures and documents with no structured candidates are **not charged**. There is no minimum batch size; cost scales with delivered results.

### Tips

- Use direct public image URLs that can be downloaded without an interactive login.
- Render each relevant PDF page as PNG, JPG or WebP before structured extraction; one page image is one input item.
- Group documents by type and use one run per type for clearer, more consistent output.
- Keep the original files available during the run; short-lived signed URLs must not expire before processing finishes.
- Treat every extracted value as a candidate and add human review for high-impact fields such as totals, account details and contract terms.

***

Built and maintained by [Brainiall](https://www.brainiall.com) — production AI APIs for speech, documents, vision and the web.

# Actor input Schema

## `documentUrls` (type: `array`):

Public HTTP or HTTPS URLs pointing directly to page images in PNG, JPG/JPEG or WebP format. The structured extractor does not accept PDF files: convert the page to an image first, or use the pdf-to-markdown Actor when you need PDF text. Each image URL produces one dataset item.

## `documentType` (type: `string`):

The document type sent for extraction. Use a supported lowercase identifier such as invoice, receipt, contract or bank\_statement. All URLs in this run use this type.

## Actor input object example

```json
{
  "documentUrls": [
    {
      "url": "https://example.com/invoice-page.png"
    }
  ],
  "documentType": "invoice"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "documentUrls": [
        {
            "url": "https://example.com/invoice-page.png"
        }
    ],
    "documentType": "invoice"
};

// Run the Actor and wait for it to finish
const run = await client.actor("vivid_astronaut/invoice-extraction").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "documentUrls": [{ "url": "https://example.com/invoice-page.png" }],
    "documentType": "invoice",
}

# Run the Actor and wait for it to finish
run = client.actor("vivid_astronaut/invoice-extraction").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "documentUrls": [
    {
      "url": "https://example.com/invoice-page.png"
    }
  ],
  "documentType": "invoice"
}' |
apify call vivid_astronaut/invoice-extraction --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vivid_astronaut/invoice-extraction"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WAlJNyEfJ66g9oshy/builds/ovKc1Vw6WHqFa9eJ2/openapi.json