POST /api/v1/extract

Submit a document for extraction. Returns a job ID immediately — processing is asynchronous.

Requires authentication.

Endpoint

POST /api/v1/extract
Content-Type: multipart/form-data
Authorization: Bearer <api_key>

Request fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | file | File | Yes | Document to extract from. Max 50 MB. | | extract | JSON string | Yes | Extraction instructions — see format below. |

The extract field

This is the core of the API. It is a JSON string with two parts:

{
  "document_type": "invoice",
  "fields": {
    "invoice_number": "invoice reference number",
    "vendor_name":    "name of the seller or vendor",
    "total":          "final total amount due",
    "date":           "date the invoice was issued"
  }
}

| Key | Required | Description | |-----|----------|-------------| | document_type | No | Plain-English hint that helps the extraction engine understand context. E.g. "invoice", "medical consultation", "offer letter". | | fields | Yes | Object where each key becomes a key in the result JSON, and the value describes what to look for. |

Field key rules:

• Must start with a letter
• Letters, digits, and underscores only
• Max 64 characters
• Max 50 fields per request

Examples

Invoice

curl -X POST "https://exdocapi.cheapehai.shop/api/v1/extract" \
  -H "Authorization: Bearer $EXDOC_API_KEY" \
  -F "file=@invoice.pdf" \
  -F 'extract={"document_type":"invoice","fields":{"invoice_number":"invoice reference ID","vendor_name":"name of the seller","total":"final amount due","date":"date invoice was issued","due_date":"payment due date"}}'

Medical consultation

curl -X POST "https://exdocapi.cheapehai.shop/api/v1/extract" \
  -H "Authorization: Bearer $EXDOC_API_KEY" \
  -F "file=@consultation.pdf" \
  -F 'extract={"document_type":"medical consultation","fields":{"patient_name":"full name of patient","diagnosis":"condition diagnosed","prescription":"medicines prescribed","follow_up":"next appointment date"}}'

Employment contract

curl -X POST "https://exdocapi.cheapehai.shop/api/v1/extract" \
  -H "Authorization: Bearer $EXDOC_API_KEY" \
  -F "file=@contract.pdf" \
  -F 'extract={"document_type":"employment contract","fields":{"employee_name":"name of the employee","designation":"job title","joining_date":"start date","salary":"compensation offered","notice_period":"notice period required"}}'

Response — 201 Created

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "page_count": 2
}

| Field | Description | |-------|-------------| | job_id | UUID — use this to poll status and fetch results | | status | pending (direct dispatch) or queued (queue mode) | | page_count | Pages detected — equals credits that will be deducted on completion |

Error responses

| Status | Body | Cause | |--------|------|-------| | 400 | file is required | No file attached | | 400 | extract is required | No extract field | | 400 | fields must be an object | Passed an array instead of object | | 400 | fields cannot be empty | Empty fields object | | 400 | Maximum 50 fields per request | Too many fields | | 400 | File too large. Maximum size is 50MB. | File exceeds limit | | 401 | Invalid API key | Bad or missing key | | 402 | Insufficient credits | Not enough credits |