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. See Authentication for how to create and use your API key.
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.
/v1/extract
Headers
| Header | Value |
|---|---|
| Authorization | Bearer YOUR_API_KEY |
| Content-Type | multipart/form-data |
Parameters (form-data)
| Parameter | Type | Required | Description |
|---|---|---|---|
| file | File | Yes | The document to extract data from (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF) |
| schema_id | String | No | Schema 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
}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.
/v1/upload
Upload a document and receive a file_id for extraction.
Parameters (form-data)
| Parameter | Type | Required | Description |
|---|---|---|---|
| file | File | Yes | The document to upload (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF) |
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
}/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
| Header | Value |
|---|---|
| Authorization | Bearer YOUR_API_KEY |
| Content-Type | application/json |
Parameters (JSON body)
| Parameter | Type | Required | Description |
|---|---|---|---|
| file_id | String | Yes | The file ID returned from the upload endpoint |
| schema_id | String | No | Schema 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"
}/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
}Export to CSV / Excel
Convert a completed extraction's result into a spreadsheet. Exports are free, repeatable, and do not consume pages. Nested arrays are denormalized: header fields repeat on every row, so the output is ready for pivot tables and imports. Tip: pass output_format (csv or xlsx) on the extract request and the export starts automatically as soon as the extraction completes.
/v1/extractions/:id/export
Start the export. Idempotent per format: repeated calls return the running conversion or the finished file's status.
Example
curl -X POST https://api-parse.conversiontools.io/v1/extractions/ext_789.../export \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"format": "xlsx"}'Response
{
"success": true,
"status": "processing",
"format": "xlsx",
"progress": 0
}/v1/extractions/:id/export?format=xlsx
Poll the export. While converting, the response is JSON with status: "processing" and a progress percentage. When ready, the response body is the file itself (with Content-Disposition: attachment).
Example
curl -L -o invoice.xlsx \
"https://api-parse.conversiontools.io/v1/extractions/ext_789.../export?format=xlsx" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/extractions/:id
Delete an extraction and all of its stored data (result and any export files). Source documents are always deleted automatically within 24 hours of processing; extracted results are stored until you delete them - via this endpoint or from the dashboard.
Example
curl -X DELETE https://api-parse.conversiontools.io/v1/extractions/ext_789... \
-H "Authorization: Bearer YOUR_API_KEY"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
}
}