API v2 Reference

Authentication

All v2 endpoints require a valid API key in the X-API-Key header. Generate yours from the dashboard.

X-API-Key: isin_your_key_here

Extraction Tiers

Choose a tier based on the complexity of your documents. Pass the tier name in the tier form field.

standard

Standard

Fast and cost-effective. Best for clean, simple documents like invoices, receipts, or forms with predictable layouts.

advanced Default

Advanced

Recommended for most use cases. Balances quality, speed, and cost — handles complex layouts, multi-column text, and mixed content well.

precision

Precision

Highest fidelity extraction. Best for high-stakes documents — legal contracts, financial reports, medical records — where accuracy is critical.

How It Works

1

Submit

POST your document + schema. Get a job ID back immediately.

2

Poll

GET the job using its ID. Check status — poll every few seconds.

3

Read

When status: COMPLETED, the data field has your structured result.

POST /api/v2/extract multipart/form-data · returns 202

Submit a structured extraction job. Returns immediately with a job object.

Request fields

Field	Type	Required	Description
`file`	File	required	Documents: PDF, DOCX, DOC, WPS Slides: PPTX, PPT, Keynote Spreadsheets: XLSX, XLS, CSV Images: PNG, JPG/JPEG, TIFF
`schema`	JSON string	required	JSON Schema object defining the fields to extract (see example below)
`tier`	string	optional	`standard` · `advanced` (default) · `precision`
`system_prompt`	string	optional	Custom extraction instructions, e.g. "Focus on the most recent fiscal year"
`extraction_target`	string	optional	`per_doc` (default) · `per_page` · `per_table_row`

Schema example

Define each field with a type and a description. The description guides the extraction model.

{
  "type": "object",
  "properties": {
    "vendor_name":   { "type": "string",  "description": "Name of the vendor or supplier" },
    "invoice_date":  { "type": "string",  "description": "Invoice date in ISO 8601 format" },
    "total_amount":  { "type": "number",  "description": "Total invoice amount including tax" },
    "currency":      { "type": "string",  "description": "Currency code, e.g. USD or EUR" },
    "line_items": {
      "type": "array",
      "description": "Individual line items on the invoice",
      "items": {
        "type": "object",
        "properties": {
          "description": { "type": "string", "description": "Item description" },
          "quantity":    { "type": "number", "description": "Quantity ordered" },
          "unit_price":  { "type": "number", "description": "Price per unit" }
        }
      }
    }
  }
}

curl — Step 1: Submit

curl -X POST https://your-domain/api/v2/extract \
  -H "X-API-Key: isin_your_key_here" \
  -F "file=@invoice.pdf" \
  -F 'schema={"type":"object","properties":{"vendor_name":{"type":"string","description":"Vendor name"},"total_amount":{"type":"number","description":"Total amount due"}}}' \
  -F "tier=advanced"

Response (202 Accepted)

{
  "id": "isin-a3f72c1b",
  "status": "PENDING",
  "tier": "advanced",
  "created_at": "2026-07-17T10:23:45Z",
  "updated_at": "2026-07-17T10:23:45Z",
  "data": null,
  "error_message": null,
  "error_code": null,
  "metadata": {}
}

GET /api/v2/extract/{job_id}

Retrieve a job by ID. Poll every 2–5 seconds until status is COMPLETED or FAILED.

Status	Meaning
PENDING	Queued, not yet started
RUNNING	Actively processing
COMPLETED	Finished — `data` is populated
FAILED	Error — see `error_message` and `error_code`
CANCELLED	Cancelled by user

curl — Step 2: Poll

curl https://your-domain/api/v2/extract/isin-a3f72c1b \
  -H "X-API-Key: isin_your_key_here"

Response when COMPLETED

{
  "id": "isin-a3f72c1b",
  "status": "COMPLETED",
  "tier": "advanced",
  "created_at": "2026-07-17T10:23:45Z",
  "updated_at": "2026-07-17T10:24:12Z",
  "data": {
    "vendor_name": "Acme Supplies Ltd.",
    "total_amount": 4850.00
  },
  "error_message": null,
  "error_code": null,
  "metadata": { "processing_time_ms": 4820 }
}

GET /api/v2/extract

List extraction jobs for the authenticated API key, newest first.

?limit=20 — max results (1–100) ?offset=0 — pagination offset

curl "https://your-domain/api/v2/extract?limit=10" \
  -H "X-API-Key: isin_your_key_here"

GET /api/v2/health

Returns provider configuration status. Requires a valid API key.

{
  "status": "ok",
  "version": "2.0",
  "providers": {
    "extraction_engine": { "configured": true, "status": "ready" },
    "local_fallback":    { "configured": true, "status": "ready" }
  }
}

Error codes

Code	Meaning
401	Missing or invalid API key
403	You do not own the requested job
400	Bad request — empty file or invalid JSON schema
404	Job ID not found
422	Unsupported file type, or invalid `tier` / `extraction_target` value