Name: Invoice Data Extraction API: PDF and Image to JSON
Brand: td-data-systems
SKU: api-td-data-systems-invoice-data-extraction-api
Availability: InStock
Author: API Market

Tddatasystems

# Invoice Data Extraction API

## Overview

The Invoice Data Extraction API reads an invoice and returns its header and totals as validated JSON: supplier name, invoice number, invoice date, due date, subtotal, tax, total and currency. It has two endpoints that return the same response shape. Use the text endpoint when you already have the invoice as text, for example from an email body, a PDF parser or your own OCR. Use the file endpoint to upload the invoice itself as a PDF, PNG, JPEG, WebP or TIFF file. For PDFs with a text layer the API reads the text directly; for images and scanned pages it runs OCR first. Every result is checked before it is returned, and an invoice that is missing a required field is reported as invalid instead of being filled with a guessed value.

The API is built for developers working on accounts payable automation, accounting and ERP integrations, and document processing pipelines who want invoice fields in a predictable format without running their own OCR and parsing stack. Dates come back as `YYYY-MM-DD`, amounts as decimal strings such as `"156.00"`, and currency as a three-letter code. Alongside the data, each response tells you whether validation passed, a confidence score, how each field was found (`deterministic` parsing or the `local-semantic` model), whether OCR was used, and `external_ai_used`, which shows whether any outside AI service was involved. In all of our tests it was `false`: the provider runs extraction on its own infrastructure.

## Features

*   **2 endpoints**: Extract from invoice text (JSON body) or from an uploaded invoice file (multipart form).
*   **Text, PDF and image input**: Text up to 200,000 characters; files in PDF, PNG, JPEG, WebP or TIFF format up to 7 MiB, with PDFs limited to 10 pages.
*   **Text layer first, OCR when needed**: PDFs with selectable text are read directly. Images and scanned pages go through OCR (Tesseract), and the `ingestion` block tells you which path was used.
*   **Deterministic parsing with a local model fallback**: Fields are first parsed with rules. A model running on the provider's own servers fills fields the rules could not settle, and the `provenance` map labels each field `deterministic` or `local-semantic`.
*   **Validated output**: `invoice_number`, `invoice_date`, `total_amount` and `currency` are required for a valid result. Optional fields are only returned when the invoice supports them.
*   **Date order control**: Pass `date_order` as `DMY` or `MDY` to resolve numeric dates such as `03/04/2026`.
*   **Rate limit**: 1 request per second on every plan.

## Use Cases

*   **Accounts payable intake**: Turn supplier invoices that arrive by email or upload into records your AP system can match and approve.
*   **Accounting and ERP integrations**: Prefill bills in accounting software with supplier, number, dates, totals and currency.
*   **Document processing pipelines**: Add an invoice step to a pipeline that already extracts text, using the text endpoint to skip OCR.
*   **Scanned and photographed invoices**: Read invoices that only exist as images, with OCR handled by the API.
*   **Data checks before posting**: Use `valid`, `validation_status` and `warnings` to route incomplete invoices to a person instead of posting them.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/td-data-systems/invoice-data-extraction-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Extract invoice data from text

Extracts and validates invoice fields from plain invoice text. Use it when you already have the text of the invoice. No OCR is involved, so this is the fastest option: our test returned in about 1 second.

**Method:** `POST`

**Endpoint:** `/v1/invoice/extract`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `text` | body | The invoice text to extract. Line breaks can be kept as `\n`. | string | Yes | - | 200,000 characters |
| `date_order` | body | How to read ambiguous numeric dates: `DMY` (day first) or `MDY` (month first). | string | No | - | - |

The body accepts only these two fields. Any other field is rejected.

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/td-data-systems/invoice-data-extraction-api/v1/invoice/extract" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Supplier: Example Supplies Ltd\nInvoice Number: INV-2044\nInvoice Date: 08 October 2026\nDue Date: 07 November 2026\nSubtotal: GBP 250.00\nVAT: GBP 50.00\nTotal: GBP 300.00","date_order":"DMY"}'
```

**Example Response (200 OK):**

```json
{
  "billing_units": null,
  "confidence": 1.0,
  "data": {
    "currency": "GBP",
    "due_date": "2026-11-07",
    "invoice_date": "2026-10-08",
    "invoice_number": "INV-2044",
    "subtotal_amount": "250.00",
    "supplier_name": "Example Supplies Ltd",
    "tax_amount": "50.00",
    "total_amount": "300.00"
  },
  "error_category": "",
  "external_ai_used": false,
  "job_id": "34156ef3-679b-4c3c-8250-b541fc5c4cf6",
  "job_status": "COMPLETED",
  "model": null,
  "model_provider": null,
  "processing_seconds": 0.000575,
  "product_id": "structured-data.invoice.text",
  "provenance": {
    "currency": "deterministic",
    "due_date": "deterministic",
    "invoice_date": "deterministic",
    "invoice_number": "deterministic",
    "subtotal_amount": "deterministic",
    "supplier_name": "deterministic",
    "tax_amount": "deterministic",
    "total_amount": "deterministic"
  },
  "request_source": "MARKETPLACE",
  "schema_version": "1.0",
  "semantic_available": true,
  "semantic_error": null,
  "semantic_usage": {},
  "semantic_used": false,
  "usage_units": 1,
  "valid": true,
  "validation_status": "PASSED",
  "warnings": []
}
```

Key response fields:

*   **`data`**: The extracted invoice fields. Dates are `YYYY-MM-DD`; amounts are decimal strings.
*   **`valid`** and **`validation_status`**: `true` and `PASSED` when all required fields were found and checked.
*   **`confidence`**: An overall confidence score for the result.
*   **`provenance`**: How each field was found. `deterministic` means rule-based parsing of the text; `local-semantic` means the field was filled by the model that runs on the provider's own servers.
*   **`semantic_used`**: `true` when the local model was needed for at least one field. Here every field was parsed by rules, so it is `false`.
*   **`external_ai_used`**: `false` when no outside AI service was involved.
*   **`warnings`**: Notes about the input or the result, such as a field that could not be confirmed.
*   **`job_id`** and **`job_status`**: An ID for the request and its outcome (`COMPLETED` on success).

#### 2. Extract invoice data from a PDF or image

Extracts and validates invoice fields from one uploaded invoice file. PDFs with a text layer are read directly; images and scanned PDFs are run through OCR. The response has the same fields as the text endpoint, plus an `ingestion` block that describes how the file was read. In our tests a one-page PDF returned in about 3 seconds and a one-page PNG through OCR in about 7 seconds.

**Method:** `POST`

**Endpoint:** `/v1/invoice/extract-file`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `file` | form | The invoice file: PDF, PNG, JPEG, WebP or TIFF. One file per request. | file | Yes | - | 7 MiB; PDFs up to 10 pages |
| `date_order` | form | How to read ambiguous numeric dates: `DMY` (day first) or `MDY` (month first). | string | No | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/td-data-systems/invoice-data-extraction-api/v1/invoice/extract-file" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"
```

**Example Response (200 OK, abridged):**

This is the result for a one-page PDF invoice from Northgate Supplies Ltd. The `model` and `semantic_usage` fields are shortened.

```json
{
  "billing_units": null,
  "confidence": 1.0,
  "data": {
    "currency": "GBP",
    "due_date": "2026-11-07",
    "invoice_date": "2026-10-08",
    "invoice_number": "INV-1001",
    "subtotal_amount": "130.00",
    "supplier_name": "Northgate Supplies Ltd",
    "tax_amount": "26.00",
    "total_amount": "156.00"
  },
  "error_category": "",
  "external_ai_used": false,
  "ingestion": {
    "input_type": "PDF_TEXT",
    "ocr_engine": null,
    "ocr_used": false,
    "page_count": 1,
    "text_layer_used": true,
    "warnings": []
  },
  "invoice_processing_seconds": 2.00875,
  "job_id": "c43977d6-dc79-49f9-a980-2257d3e4a3b9",
  "job_status": "COMPLETED",
  "model_provider": "local",
  "processing_seconds": 2.027818,
  "product_id": "structured-data.invoice.document",
  "provenance": {
    "currency": "deterministic",
    "due_date": "deterministic",
    "invoice_date": "deterministic",
    "invoice_number": "deterministic",
    "subtotal_amount": "deterministic",
    "supplier_name": "deterministic",
    "tax_amount": "local-semantic",
    "total_amount": "deterministic"
  },
  "request_source": "MARKETPLACE",
  "schema_version": "1.0",
  "semantic_available": true,
  "semantic_error": null,
  "semantic_usage": {
    "content": "{\n  \"tax_amount\": \"26.00\"\n}",
    "cost": 0.0,
    "usage": {
      "completion_tokens": 15,
      "prompt_tokens": 557,
      "prompt_tokens_details": {
        "cached_tokens": 118
      },
      "total_tokens": 572
    }
  },
  "semantic_used": true,
  "usage_units": 1,
  "valid": true,
  "validation_status": "PASSED",
  "warnings": []
}
```

In this result `tax_amount` was settled by the local model (`local-semantic`), and `semantic_usage` shows what that model returned and the tokens it used. `model_provider` is `local` and `cost` is `0.0`: the model runs on the provider's own servers.

When you upload an image, the same invoice comes back with identical `data`, and the `ingestion` block shows that OCR was used:

```json
{
  "input_type": "IMAGE_OCR",
  "ocr_engine": "tesseract 5.3.4",
  "ocr_used": true,
  "page_count": 1,
  "text_layer_used": false,
  "warnings": [
    "image OCR used for PNG"
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The invoice was extracted and validated. `valid` is `true` and `validation_status` is `PASSED`. |
| 400 | Bad Request | The request could not be processed: `text` or `file` is missing, the JSON body is malformed or has unknown fields, `date_order` is not `DMY` or `MDY`, or the `x-api-market-key` header is missing. For files, OCR may also find no readable text, which returns `"error": "ocr_no_usable_text"` with `job_status` `REJECTED`. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path does not exist. Check the base URL and the endpoint path. |
| 408 | Request Timeout | OCR or document processing on the uploaded file took too long. Try a smaller file or fewer pages. |
| 413 | Payload Too Large | The text is over 200,000 characters, the file is over 7 MiB, or the PDF has more than 10 pages. |
| 415 | Unsupported Media Type | The uploaded file is not a PDF, PNG, JPEG, WebP or TIFF. |
| 422 | Unprocessable Entity | Extraction ran, but the result could not be validated as a complete invoice. The body has `valid: false`, the `validation_status` and `warnings` explaining what was missing. |
| 429 | Too Many Requests | You went over 1 request per second, or you have used your plan's request quota. |
| 500 | Internal Server Error | Something failed while processing the invoice. Retry after a short delay. |
| 503 | Service Unavailable | The service is temporarily unavailable or OCR capacity is busy. Retry after a short delay. |

## Rate Limits

Every plan (BASIC, Pro, Ultra and Mega) allows 1 request per second, across both endpoints. Each plan also has a hard request quota: 20 requests on BASIC, 500 on Pro, 2,000 on Ultra and 5,000 on Mega. Requests over the per-second limit or past the quota return `429 Too Many Requests`. If you are processing a batch of invoices, send them one at a time with at least one second between requests, back off when you get a `429`, and honour any `Retry-After` header before retrying.

## FAQ

**Which fields does the API return?**

Supplier name, invoice number, invoice date, due date, subtotal, tax amount, total amount and currency. Invoice number, invoice date, total and currency are required for a valid result; the other fields are returned when the invoice contains them.

**Does it extract line items, PO numbers or addresses?**

No. The API covers the invoice header and totals only. In our test the sample invoice had two line items, a PO reference and a supplier address, and none of these were returned. If you need line items, extract them separately.

**What do `deterministic` and `local-semantic` mean in `provenance`?**

`deterministic` means the field was read by rule-based parsing of the invoice text. `local-semantic` means the rules could not settle the field and it was filled by a language model running on the provider's own servers. `semantic_used` is `true` whenever at least one field came from the model. You can use `provenance` to send model-filled fields for review if your process requires it.

**Is my invoice sent to an outside AI service?**

The provider states that invoices are processed on its own infrastructure, and every response includes `external_ai_used` so you can check it per request. It was `false` in all of our tests, and `model_provider` was `local` whenever the model was used.

**Why did my image return `ocr_no_usable_text`?**

OCR could not read enough text from the image to find an invoice, which returns `400` with `job_status` `REJECTED`. In our tests this happened with a small, low-resolution PNG, while a larger, sharper PNG of the same invoice extracted correctly. Send a higher-resolution scan with clear, upright text, or upload the original PDF if you have it, since a PDF with a text layer skips OCR entirely.

**What happens if an invoice is missing a required field?**

The API does not invent a value. If it cannot find and validate the invoice number, invoice date, total or currency, it returns `422` with `valid: false`, a `validation_status` and `warnings` describing the problem, so you can route the invoice to manual review.

**How are dates like 03/04/2026 handled?**

Pass `date_order` as `DMY` to read them as day first (3 April) or `MDY` for month first (March 4). Dates written with a month name, such as `08 October 2026`, are not ambiguous. All dates are returned as `YYYY-MM-DD`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Invoice data extraction API that returns supplier, invoice number, dates, subtotal, tax, total and currency as validated JSON from text, PDFs and images.

Invoice Data Extraction API: PDF and Image to JSON

BASIC