Parse Document

POST/v1/parse

Upload a document image for parsing. The API processes the image through OCR and AI extraction, returning structured data as JSON.

Request

Send as multipart/form-data.

Parameter	Type	Required	Description
`file`	file	Yes	Document image. JPEG, PNG, or WebP. Max 10 MB.
`document_type`	string	No	Document category. Auto-detected if omitted.
`document_brand`	string	No	Regional variant. Auto-detected if omitted.
`deep_scan`	boolean	No	Enable enhanced extraction with additional processing. Defaults to `false`.
`background`	boolean	No	Queue processing and return `202 Accepted` immediately. Poll `GET /v1/parse/:id` or use `webhook_url` to get results. Defaults to `false`.
`webhook_url`	string	No	HTTPS URL to receive a POST callback when processing completes. Requires `background=true`. The domain must be whitelisted in Dashboard > Webhooks.

Document types

identity_cardpassportdriving_licensework_permitbirth_certificateother

Document brands

mykadmyprmykasktpnricthai_idthai_dl

Examples

curl -X POST https://api.dokai.dev/v1/parse \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -F "[email protected]" \
  -F "document_type=identity_card" \
  -F "document_brand=mykad"

Background processing

Set background=true to queue the document for async processing. The API returns 202 Accepted immediately. Optionally pass a webhook_url to receive a POST callback when processing completes.

The webhook URL's domain must be whitelisted in your Dashboard under Webhooks settings.

cURL — background with webhook

curl -X POST https://api.dokai.dev/v1/parse \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -F "[email protected]" \
  -F "background=true" \
  -F "webhook_url=https://hooks.example.com/dokai"

202 Accepted

{
  "id": "parse_abc123",
  "status": "pending",
  "message": "Document queued for processing."
}

Response

Returns 200 OK with the parsed result (synchronous), or 202 Accepted when background=true.

200 OK

{
  "id": "parse_abc123",
  "status": "success",
  "document_type": "identity_card",
  "document_brand": "mykad",
  "data": {
    "name": "AHMAD BIN IBRAHIM",
    "ic_number": "880503-14-5523",
    "date_of_birth": "1988-05-03",
    "gender": "male",
    "nationality": "WARGANEGARA",
    "address": {
      "line1": "No 42, Jalan Bukit Bintang",
      "postcode": "55100",
      "city": "Kuala Lumpur",
      "state": "Wilayah Persekutuan"
    }
  },
  "extra": {
    "religion": "ISLAM",
    "race": "MELAYU"
  },
  "metadata": {
    "processing_time_ms": 1420,
    "ocr_confidence": 0.95,
    "extraction_confidence": 0.97,
    "tokens_input": 1250,
    "tokens_output": 340,
    "estimated_cost": 0.0042
  },
  "created_at": "2026-03-06T10:30:00Z",
  "expires_at": "2026-03-13T10:30:00Z"
}

Response fields

Field	Type	Description
`id`	string	Unique parse result identifier
`status`	string	`pending`, `processing`, `success`, or `failed`
`document_type`	string	Detected or specified document category
`document_brand`	string \| null	Regional document variant, if identified
`data`	object	Extracted document fields (varies by document type)
`extra`	object \| null	Additional extracted fields not in the primary schema
`metadata`	object	Processing details (time, model, confidence, cost)
`created_at`	string	ISO 8601 timestamp
`expires_at`	string	When the result will be purged (based on plan retention)