API Documentation

Everything you need to integrate ParseFlow into your application. Complete API reference with examples in 5 languages.

Authentication

All API requests require an API key. Get your key from the Dashboard.

Include your key in the X-API-Key header:

curl -X POST https://parseflow.dev/api/v1/extract \
  -H "X-API-Key: dm_live_your_api_key_here" \
  -F "file=@document.pdf"

Alternatively, use Authorization: Bearer dm_live_.... See the full Authentication Guide for key rotation and security best practices.

Base URL

https://parseflow.dev

All endpoints are relative to this base URL. HTTPS is required for all requests.

Endpoints

Method	Endpoint	Description	Auth
POST	/api/v1/extract	Extract structured data from a document	Required
GET	/api/v1/documents/:id	Retrieve a previous extraction result	Required
POST	/api/v1/batch	Upload multiple documents at once	Required
POST	/api/v1/demo	Demo extraction (no API key, 2MB limit)	None

Upload Document

POST /api/v1/extract

Upload a document and receive structured extracted data.

Request Parameters

Field	Type	Required	Description
file	File	Yes	PDF, JPG, PNG, WebP, or TIFF
document_type	String	No	auto, invoice, receipt, contract, id_document, bank_statement
language	String	No	ISO 639-1 code (auto-detected if omitted)

Code Examples

curl -X POST https://parseflow.dev/api/v1/extract \
  -H "X-API-Key: dm_live_your_api_key" \
  -F "file=@invoice.pdf" \
  -F "document_type=invoice"

Example Response

{
  "id": "ext_7f3a2b1c-4d5e-6f78-9a0b-cdef12345678",
  "status": "completed",
  "documentType": "invoice",
  "confidence": 0.92,
  "data": {
    "type": "invoice",
    "invoiceNumber": "INV-2026-0142",
    "invoiceDate": "March 15, 2026",
    "dueDate": "April 14, 2026",
    "vendor": {
      "name": "Acme Corporation",
      "email": "billing@acme.com"
    },
    "lineItems": [
      {
        "description": "API Integration Service",
        "quantity": 1,
        "unitPrice": 2500.00,
        "amount": 2500.00
      }
    ],
    "subtotal": 7500.00,
    "taxAmount": 618.75,
    "taxRate": 8.25,
    "total": 8118.75,
    "currency": "USD"
  },
  "metadata": {
    "fileName": "invoice.pdf",
    "fileSize": 45231,
    "mimeType": "application/pdf",
    "pageCount": 1,
    "language": "en"
  },
  "processingTimeMs": 342
}

Get Results

GET /api/v1/documents/:id

Retrieve a previous extraction result by its ID. Results are stored for 90 days.

Path Parameters

Parameter	Description
id	The extraction ID returned from POST /api/v1/extract (e.g., ext_7f3a2b1c...)

Code Examples

curl https://parseflow.dev/api/v1/documents/ext_7f3a2b1c... \
  -H "X-API-Key: dm_live_your_api_key"

Batch Upload

POST /api/v1/batch

Process multiple documents in a single request. Available on Starter plan and above.

Plan	Max Files per Batch
Free	3
Starter	10
Pro	50
Enterprise	Unlimited

curl -X POST https://parseflow.dev/api/v1/batch \
  -H "X-API-Key: dm_live_your_api_key" \
  -F "files[]=@invoice1.pdf" \
  -F "files[]=@invoice2.pdf" \
  -F "files[]=@receipt.jpg" \
  -F "document_type=auto"

Learn more about batch processing on the Batch Processing page.

Response Format

All responses follow this structure:

{
  "id": "string",          // Unique extraction ID
  "status": "string",      // "completed" | "processing" | "failed"
  "documentType": "string",// Detected or specified document type
  "confidence": 0.92,      // 0-1 confidence score
  "data": { ... },         // Structured extracted data (varies by type)
  "metadata": {
    "fileName": "string",
    "fileSize": 0,
    "mimeType": "string",
    "pageCount": 0,
    "language": "string"
  },
  "createdAt": "string",   // ISO 8601 timestamp
  "processingTimeMs": 0    // Processing time in milliseconds
}

See Supported Formats for the full list of supported document types and their output schemas.

Error Codes

All errors return a JSON body with error and code fields:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Code	HTTP	Description
AUTH_MISSING	401	No API key provided in request headers.
AUTH_INVALID	401	API key is invalid, expired, or revoked.
RATE_LIMITED	429	Too many requests. Check Retry-After header.
QUOTA_EXCEEDED	429	Monthly document quota exceeded.
FILE_MISSING	400	No file was included in the request.
FILE_TYPE_INVALID	400	Unsupported file format.
FILE_TOO_LARGE	400	File exceeds plan size limit.
INVALID_DOCUMENT_TYPE	400	Invalid document_type parameter.
BATCH_TOO_LARGE	400	Too many files in batch request.
EXTRACTION_FAILED	422	Could not extract text from document.
NOT_FOUND	404	Requested document/extraction not found.
INTERNAL_ERROR	500	Server error. Contact support if persists.

Rate Limits

API requests are rate limited per API key. Rate limit headers are included in every response:

X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the window resets
Retry-After — Seconds to wait (only on 429 responses)

Plan	Requests/min	Documents/month	Max File Size
Free	60	100	5 MB
Starter	60	1,000	20 MB
Pro	60	10,000	50 MB
Enterprise	120	100,000	100 MB

API Flow Diagram

The typical document processing flow:

                    ParseFlow API Flow
                    ==================

  Client                         ParseFlow API
    |                                  |
    |   POST /api/v1/extract           |
    |   [file + document_type]         |
    |--------------------------------->|
    |                                  |
    |                          +-------+-------+
    |                          |  Validate     |
    |                          |  - Auth key   |
    |                          |  - File type  |
    |                          |  - File size  |
    |                          +-------+-------+
    |                                  |
    |                          +-------+-------+
    |                          |  Process      |
    |                          |  - OCR (img)  |
    |                          |  - Parse text |
    |                          |  - Extract    |
    |                          |    fields     |
    |                          +-------+-------+
    |                                  |
    |   200 OK                         |
    |   { id, status, data, ... }      |
    |<---------------------------------|
    |                                  |
    |   GET /api/v1/documents/:id      |
    |   (retrieve later)               |
    |--------------------------------->|
    |                                  |
    |   200 OK                         |
    |   { id, status, data, ... }      |
    |<---------------------------------|

Complete Integration Examples

Full working examples for each language, including error handling:

Python — Full Example with Error Handling

import requests
import sys

API_KEY = "dm_live_your_api_key"
BASE_URL = "https://parseflow.dev"

def extract_document(file_path, doc_type="auto"):
    """Extract data from a document with error handling."""
    try:
        with open(file_path, "rb") as f:
            response = requests.post(
                f"{BASE_URL}/api/v1/extract",
                headers={"X-API-Key": API_KEY},
                files={"file": f},
                data={"document_type": doc_type},
                timeout=30
            )

        if response.status_code == 200:
            result = response.json()
            print(f"Extracted {result['documentType']}")
            print(f"Confidence: {result['confidence']:.0%}")
            return result

        elif response.status_code == 429:
            retry = response.headers.get("Retry-After", 60)
            print(f"Rate limited. Retry in {retry}s")

        else:
            error = response.json()
            print(f"Error: {error['code']} - {error['error']}")

    except requests.exceptions.Timeout:
        print("Request timed out")
    except FileNotFoundError:
        print(f"File not found: {file_path}")

    return None

# Usage
result = extract_document("invoice.pdf", "invoice")
if result:
    print(f"Total: {result['data']['total']}")

JavaScript — Full Example with Error Handling

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const API_KEY = 'dm_live_your_api_key';
const BASE_URL = 'https://parseflow.dev';

async function extractDocument(filePath, docType = 'auto') {
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  form.append('document_type', docType);

  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/extract`,
      form,
      {
        headers: {
          'X-API-Key': API_KEY,
          ...form.getHeaders()
        },
        timeout: 30000
      }
    );

    console.log(`Extracted: ${response.data.documentType}`);
    console.log(`Confidence: ${(response.data.confidence * 100).toFixed(0)}%`);
    return response.data;

  } catch (error) {
    if (error.response?.status === 429) {
      const retry = error.response.headers['retry-after'] || 60;
      console.log(`Rate limited. Retry in ${retry}s`);
    } else if (error.response) {
      console.error(`Error: ${error.response.data.code}`);
    } else {
      console.error(`Request failed: ${error.message}`);
    }
    return null;
  }
}

// Usage
const result = await extractDocument('invoice.pdf', 'invoice');
if (result) {
  console.log(`Total: ${result.data.total}`);
}

SDKs & Libraries

Official and community SDKs for easier integration:

PythonOfficial

pip install parseflow

Node.jsOfficial

npm install @parseflow/sdk

GoCommunity

go get github.com/parseflow/go-sdk

RubyCommunity

gem install parseflow