Document Extraction

Extract structured data from any document with a single API call. Send one or more files and a schema defining the fields you need, and receive typed, validated results with confidence scores and source citations.

Key Features

• Multi-Format Support — Extract from PDF, DOCX, XLSX, images, HTML, Markdown, CSV, JSON, and plain text.
• 17 Field Types — Text, numbers, dates, booleans, enums, emails, IBANs, countries, currencies, addresses, arrays, and calculated fields.
• Structured Arrays — Extract repeating data like invoice line items with nested schemas.
• Calculated Fields — Define arithmetic operations (sum, subtract, multiply, divide) computed from other extracted fields.
• Confidence Scores — Every extracted value includes a confidence score between 0 and 1.
• Source Citations — Verbatim quotes from the document that support each extracted value.
• Schema Validation — Field schemas are validated before extraction, catching errors like circular dependencies or type mismatches early.

Overview

The Document Extraction API analyzes documents and extracts structured data based on a schema you define. You send one or more files (base64 or URL) and a schema with field definitions, and receive a JSON response with typed values, confidence scores, and citations.

Endpoint: POST /document-extraction/v1/extract

Supported formats: PDF, DOCX, XLSX/XLS, CSV, TXT, Markdown, JSON, HTML, PNG, JPEG, GIF, WebP

Limits:

• Max file size: 50 MB per file

Request Format

curl -X POST https://api.iterationlayer.com/document-extraction/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "type": "base64",
        "name": "invoice.pdf",
        "base64": "<base64-encoded-file>"
      }
    ],
    "schema": {
      "fields": [
        { "name": "invoice_number", "type": "TEXT", "description": "The invoice number" },
        { "name": "total_amount", "type": "CURRENCY_AMOUNT", "description": "Total invoice amount" }
      ]
    }
  }'

import { IterationLayer } from "iterationlayer";
const client = new IterationLayer({ apiKey: "YOUR_API_KEY" });

const result = await client.extract({
  files: [
    {
      type: "base64",
      name: "invoice.pdf",
      base64: "<base64-encoded-file>",
    },
  ],
  schema: {
    fields: [
      { name: "invoice_number", type: "TEXT", description: "The invoice number" },
      { name: "total_amount", type: "CURRENCY_AMOUNT", description: "Total invoice amount" },
    ],
  },
});

from iterationlayer import IterationLayer
client = IterationLayer(api_key="YOUR_API_KEY")

result = client.extract(
    files=[
        {
            "type": "base64",
            "name": "invoice.pdf",
            "base64": "<base64-encoded-file>",
        }
    ],
    schema={
        "fields": [
            {"name": "invoice_number", "type": "TEXT", "description": "The invoice number"},
            {"name": "total_amount", "type": "CURRENCY_AMOUNT", "description": "Total invoice amount"},
        ]
    },
)

import il "github.com/iterationlayer/sdk-go"
client := il.NewClient("YOUR_API_KEY")

result, err := client.Extract(il.ExtractRequest{
    Files: []il.FileInput{il.NewFileFromBase64("invoice.pdf", "<base64-encoded-file>")},
    Schema: il.ExtractionSchema{
        "invoice_number": il.NewTextFieldConfig("invoice_number", "The invoice number"),
        "total_amount":   il.NewCurrencyAmountFieldConfig("total_amount", "Total invoice amount"),
    },
})

Top-Level Fields

Async Mode

Add a webhook_url parameter to process the request in the background. The API returns 201 Accepted immediately and delivers the result to your webhook URL when processing completes. See Webhooks for payload format and retry behavior.

File Input

Provide each file as either base64 or a URL:

URL Example

{
  "files": [
    {
      "type": "url",
      "name": "invoice.pdf",
      "url": "https://example.com/invoice.pdf"
    }
  ],
  "schema": {
    "fields": [
      { "name": "invoice_number", "type": "TEXT", "description": "The invoice number" }
    ]
  }
}

Schema Definition

The schema object contains a fields array. Each field has these base properties:

Each field type supports additional type-specific properties described below.

Field Types

TEXT

Short single-line text value.

{ "name": "company_name", "type": "TEXT", "description": "Name of the company" }

TEXTAREA

Multi-line text value.

{ "name": "notes", "type": "TEXTAREA", "description": "Additional notes or comments" }

INTEGER

Whole number value.

{ "name": "quantity", "type": "INTEGER", "description": "Number of items ordered", "min": 1 }

DECIMAL

Floating-point number value.

{ "name": "weight", "type": "DECIMAL", "description": "Package weight", "unit": "kg", "decimal_points": 2 }

DATE

Calendar date, extracted as an ISO 8601 string (YYYY-MM-DD).

{ "name": "invoice_date", "type": "DATE", "description": "Date the invoice was issued" }

DATETIME

Date and time, extracted as an ISO 8601 datetime string.

{ "name": "timestamp", "type": "DATETIME", "description": "Transaction timestamp" }

TIME

Time value (e.g., "14:30:00"). No additional parameters.

{ "name": "delivery_time", "type": "TIME", "description": "Scheduled delivery time" }

ENUM

One or more values from a predefined list. Extracted as a string array.

{
  "name": "payment_method",
  "type": "ENUM",
  "description": "How the invoice was paid",
  "values": ["bank_transfer", "credit_card", "cash", "paypal"],
  "max_selected": 1
}

BOOLEAN

True or false value.

{ "name": "is_paid", "type": "BOOLEAN", "description": "Whether the invoice has been paid" }

EMAIL

Email address string.

{ "name": "contact_email", "type": "EMAIL", "description": "Contact email address" }

IBAN

International Bank Account Number. Validated against the pattern ^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$.

{ "name": "bank_account", "type": "IBAN", "description": "Recipient IBAN" }

COUNTRY

ISO 3166-1 alpha-2 country code (e.g., "DE", "US").

{ "name": "origin_country", "type": "COUNTRY", "description": "Country of origin" }

CURRENCY_CODE

ISO 4217 currency code (e.g., "EUR", "USD").

{ "name": "currency", "type": "CURRENCY_CODE", "description": "Invoice currency" }

CURRENCY_AMOUNT

Numeric monetary amount.

{ "name": "total_amount", "type": "CURRENCY_AMOUNT", "description": "Total invoice amount", "decimal_points": 2 }

ADDRESS

Structured address object. Extracted as an object with street, city, region, postal_code, and country fields.

Response value shape:

{
  "street": "123 Main St",
  "city": "Berlin",
  "region": "Berlin",
  "postal_code": "10115",
  "country": "DE"
}

{ "name": "billing_address", "type": "ADDRESS", "description": "Billing address", "allowed_country_codes": ["DE", "AT", "CH"] }

ARRAY

A list of structured objects, each conforming to a nested schema. Use this for repeating data like line items.

The item_schema.fields array uses the same field configuration format as top-level fields.

{
  "name": "line_items",
  "type": "ARRAY",
  "description": "Invoice line items",
  "item_schema": {
    "fields": [
      { "name": "description", "type": "TEXT", "description": "Item description" },
      { "name": "quantity", "type": "INTEGER", "description": "Quantity ordered", "min": 1 },
      { "name": "unit_price", "type": "CURRENCY_AMOUNT", "description": "Price per unit", "decimal_points": 2 },
      { "name": "total", "type": "CURRENCY_AMOUNT", "description": "Line item total", "decimal_points": 2 }
    ]
  }
}

CALCULATED

A derived numeric value computed from other extracted fields. Not extracted from the document — calculated after all source fields are resolved.

Source fields must be numeric types: INTEGER, DECIMAL, CURRENCY_AMOUNT, or another CALCULATED. Circular dependencies are detected and rejected at validation time.

{
  "name": "tax_amount",
  "type": "CALCULATED",
  "description": "Tax amount (total minus net)",
  "operation": "subtract",
  "source_field_names": ["total_amount", "net_amount"]
}

Response Format

Success Response

{
  "success": true,
  "data": {
    "invoice_number": {
      "type": "TEXT",
      "value": "INV-2024-001",
      "confidence": 0.98,
      "citations": ["Invoice No: INV-2024-001"],
      "source": "invoice.pdf"
    },
    "total_amount": {
      "type": "CURRENCY_AMOUNT",
      "value": 1250.00,
      "confidence": 0.95,
      "citations": ["Total: €1,250.00"],
      "source": "invoice.pdf"
    }
  }
}

Each field in data contains:

Value types by field type:

Fields that could not be extracted and have no default_value are omitted from data (unless is_required is true, which causes an error). Fields resolved via default_value have a confidence of 1.0.

Recipes

For complete, runnable examples see the Recipes page.

• Automate Invoice Processing – Extract line items, totals, and vendor details from invoices into structured JSON.
• Parse Resumes and CVs – Pull contact info, work history, and skills from resumes into structured data.
• Extract Contract Clauses – Identify and extract specific clauses, dates, and parties from legal contracts.
• Parse Receipts and Expenses – Extract merchant, amount, date, and line items from receipt images and PDFs.
• Extract Product Catalog Data – Pull product names, prices, and specifications from catalog documents.

Error Responses

All errors return a JSON body with { "success": false, "error": "<message>" }.