> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parsefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Complete reference for the Parsefy REST API

## Base URL

All API requests should be made to:

```
https://api.parsefy.io
```

## Overview

Parsefy is an API that turns **financial PDFs** (invoices, receipts, bills) into structured JSON with validation and risk signals.

## Endpoints

| Method | Endpoint         | Description                    | Auth Required |
| ------ | ---------------- | ------------------------------ | ------------- |
| `POST` | `/v1/extract`    | Extract data from documents    | Yes           |
| `POST` | `/v1/playground` | Test extraction (rate limited) | No            |
| `GET`  | `/health`        | Health check                   | No            |
| `GET`  | `/`              | API information                | No            |

## Request Format

All document extraction requests use **multipart/form-data** encoding:

```bash theme={null}
curl -X POST "https://api.parsefy.io/v1/extract" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'output_schema={"type": "object", "properties": {...}}' \
  -F "confidence_threshold=0.85"
```

### Parameters

| Parameter              | Type    | Default  | Description                                         |
| ---------------------- | ------- | -------- | --------------------------------------------------- |
| `file`                 | File    | required | The document to process (PDF or DOCX, max 10MB)     |
| `output_schema`        | String  | required | JSON Schema defining the extraction structure       |
| `confidence_threshold` | Number  | `0.85`   | Minimum confidence before accepting results         |
| `enable_verification`  | Boolean | `false`  | Enable math verification (totals, subtotals, taxes) |

## Response Format

All successful responses include field-level confidence and evidence:

```json theme={null}
{
  "object": {
    "invoice_number": "INV-2024-0042",
    "subtotal": 1150.00,
    "tax": 100.00,
    "total": 1250.00,
    "_meta": {
      "confidence_score": 0.94,
      "field_confidence": [
        { "field": "$.invoice_number", "score": 0.98, "reason": "Exact match", "page": 1, "text": "Invoice # INV-2024-0042" },
        { "field": "$.subtotal", "score": 0.95, "reason": "Exact match", "page": 1, "text": "Subtotal: $1,150.00" },
        { "field": "$.tax", "score": 0.95, "reason": "Exact match", "page": 1, "text": "Tax: $100.00" },
        { "field": "$.total", "score": 0.92, "reason": "Formatting ambiguous", "page": 1, "text": "Total: $1,250.00" }
      ],
      "issues": []
    }
  },
  "metadata": {
    "processing_time_ms": 2340,
    "credits": 1,
    "fallback_triggered": false
  },
  "verification": {
    "status": "PASSED",
    "checks_passed": 1,
    "checks_failed": 0,
    "cannot_verify_count": 0,
    "checks_run": [
      {
        "type": "HORIZONTAL_SUM",
        "status": "PASSED",
        "fields": ["total", "subtotal", "tax"],
        "passed": true,
        "delta": 0.0,
        "expected": 1250.00,
        "actual": 1250.00
      }
    ]
  }
}
```

### Response Fields

<ResponseField name="object" type="object" required>
  The extracted data matching your schema structure.

  <Expandable title="properties">
    <ResponseField name="_meta" type="object">
      Automatically injected quality metrics and evidence.

      <Expandable title="properties">
        <ResponseField name="confidence_score" type="number">
          Overall extraction confidence from 0.0 to 1.0
        </ResponseField>

        <ResponseField name="field_confidence" type="array">
          Per-field confidence with evidence (field path, score, reason, page, source text)
        </ResponseField>

        <ResponseField name="issues" type="array">
          Array of human-readable issue descriptions
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Processing information for the request.

  <Expandable title="properties">
    <ResponseField name="processing_time_ms" type="integer">
      Total processing time in milliseconds
    </ResponseField>

    <ResponseField name="credits" type="integer">
      Credits consumed (\~1 per page, more if fallback triggered)
    </ResponseField>

    <ResponseField name="fallback_triggered" type="boolean">
      Whether the Tier 2 fallback model was used
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="verification" type="object">
  Math verification results (only present if `enable_verification` was true).

  <Expandable title="properties">
    <ResponseField name="status" type="string">
      Overall status: `PASSED`, `FAILED`, `PARTIAL`, `CANNOT_VERIFY`, or `NO_RULES`
    </ResponseField>

    <ResponseField name="checks_passed" type="integer">
      Number of verification checks that passed
    </ResponseField>

    <ResponseField name="checks_failed" type="integer">
      Number of verification checks that failed
    </ResponseField>

    <ResponseField name="cannot_verify_count" type="integer">
      Number of checks that could not be verified
    </ResponseField>

    <ResponseField name="checks_run" type="array">
      Detailed results for each verification check
    </ResponseField>
  </Expandable>
</ResponseField>

## Content Types

### Request

* **Content-Type**: `multipart/form-data`

### Response

* **Content-Type**: `application/json`

## Supported File Types

| Format         | Extension | Max Size | Processing           |
| -------------- | --------- | -------- | -------------------- |
| PDF            | `.pdf`    | 10 MB    | Native multimodal AI |
| Microsoft Word | `.docx`   | 10 MB    | Markdown conversion  |

## SDKs

We provide official SDKs for popular languages:

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="/quickstart/python/introduction">
    Use Pydantic models for type-safe extraction
  </Card>

  <Card title="Node.js" icon="node-js" href="/quickstart/node/introduction">
    Use Zod schemas with full TypeScript support
  </Card>
</CardGroup>

## Quick Links

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key setup and usage
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/rate-limits">
    Request and credit limits
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Error codes and handling
  </Card>
</CardGroup>