ParseDocumentation
DashboardGet Started

Getting Started

  • Introduction
  • Quickstart
  • Authentication

API Reference

  • POST /v1/extract
  • Schemas
  • Usage & Limits

Examples

  • Invoice Extraction
  • Receipt Parsing
  • Form Processing

API Reference

Parse offers two ways to extract data from documents: a single-call synchronous method and a three-step asynchronous method. All endpoints require a Bearer token in the Authorization header.

Base URL: https://api-parse.conversiontools.io

Method 1: Single Call (Sync)

Upload a file and get the extraction result in a single request. The server processes the document and returns the result directly. If processing takes longer than the server timeout, you will receive a 202 response with an extraction ID for polling.

POST

/v1/extract

Headers

HeaderValue
AuthorizationBearer YOUR_API_KEY
Content-Typemultipart/form-data

Parameters (form-data)

ParameterTypeRequiredDescription
fileFileYesThe document to extract data from (PDF, JPEG, PNG, WebP, TIFF)
schema_idStringNoSchema ID to control which fields to extract

Example

curl -X POST https://api-parse.conversiontools.io/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Response (200)

{
  "success": true,
  "id": "ext_789...",
  "filename": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "date": "2024-01-15",
    "total": 1650.00
  },
  "pages_used": 1,
  "confidence": 0.95
}

Response (202 — processing takes longer)

If the document takes longer to process, the server returns a 202 with an extraction ID. Poll GET /v1/extractions/:id for the result.

{
  "success": true,
  "id": "ext_789...",
  "status": "processing"
}

Method 2: Upload + Extract (Async)

A three-step flow: upload the file first, then start an extraction, then poll for the result. This method gives you more control — you can reuse the same uploaded file for multiple extractions with different schemas.

POST

/v1/upload

Upload a document and receive a file_id for extraction.

Parameters (form-data)

ParameterTypeRequiredDescription
fileFileYesThe document to upload (PDF, JPEG, PNG, WebP, TIFF)

Example

curl -X POST https://api-parse.conversiontools.io/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Response

{
  "success": true,
  "file_id": "abc123...",
  "filename": "invoice.pdf",
  "size": 52480
}
POST

/v1/extract

Start an extraction on an uploaded file using its file_id. Optionally specify a schema_id to control which fields to extract.

Headers

HeaderValue
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/json

Parameters (JSON body)

ParameterTypeRequiredDescription
file_idStringYesThe file ID returned from the upload endpoint
schema_idStringNoSchema ID to control which fields to extract

Example

curl -X POST https://api-parse.conversiontools.io/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "abc123...", "schema_id": "sch_456..."}'

Response

{
  "success": true,
  "id": "ext_789...",
  "status": "processing"
}
GET

/v1/extractions/:id

Retrieve the result of an extraction. Poll this endpoint until status is completed.

Example

curl https://api-parse.conversiontools.io/v1/extractions/ext_789... \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "id": "ext_789...",
  "filename": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "date": "2024-01-15",
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 10,
        "unit_price": 150.00,
        "amount": 1500.00
      }
    ],
    "subtotal": 1500.00,
    "tax": 150.00,
    "total": 1650.00,
    "currency": "USD"
  },
  "pages_used": 1,
  "confidence": 0.95
}

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

429 Rate Limited

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Monthly page limit exceeded",
    "limit": 100,
    "used": 100
  }
}