API Reference / Extract

Extract data from a document

Run a template against a document and receive structured, typed JSON. Submit a file URL or a base64 payload.

Overview

POSThttps://api.docmind.wistfare.com/v1/extract

The endpoint enqueues a background job and returns 202 Accepted with an extraction id immediately. Collect the result by polling GET /v1/extractions/{id} or via a webhook.

Request

cURL · file URL

curl https://api.docmind.wistfare.com/v1/extract \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "9f2a3c91-7d94-4401-94fe-cfbd6fed63f9",
    "file_url": "https://example.com/invoice.pdf",
    "filename": "invoice.pdf",
    "reference": "claim-2026-0017"
  }'

Or send the document inline as a base64 data URL:

JSON body · base64

{
  "template_id": "9f2a3c91-...",
  "file": "data:application/pdf;base64,JVBERi0xLjcK...",
  "filename": "invoice.pdf"
}

Parameters

NAMETYPEDESCRIPTION

template_idrequiredstringThe template to run. Provide this or template_slug.

template_slugoptionalstringReference a template by its slug instead of its id.

file_urlrequiredstringURL to a PDF, PNG, or JPG. Provide this or file. Recommended for larger files up to 80 MB.

fileoptionalstringThe PDF, PNG, or JPG as a base64 data URL, as an alternative to file_url. Inline files must be under 20 MB before base64 encoding.

filenameoptionalstringOriginal filename, used as a hint and for display.

referenceoptionalstringYour own case, claim, workflow, or document id. Returned on extraction records for reconciliation.

promptoptionalstringExtra instructions appended to the template’s prompt for this run.

idempotency_keyoptionalstringDedupes retries. Also accepted as the Idempotency-Key header.

Response

A 202 with the new extraction in queued status:

202 Accepted

HTTP/1.1 202 Accepted

{
  "id": "2f14eb10-6b1d-4f0e-9a3b-1c7e6d5a8b21",
  "status": "queued",
  "template_id": "9f2a3c91-7d94-4401-94fe-cfbd6fed63f9",
  "reference": "claim-2026-0017",
  "created_at": "2026-06-07T10:41:55Z"
}

Idempotency

Pass an idempotency_key to make retries safe. A repeated request with the same key returns the original extraction instead of creating a duplicate — essential when a network error leaves you unsure whether the first call landed.

Rate limits applyThe platform respects a strict upstream ceiling and fair-shares capacity across organizations. See Rate limits for how throttling and backoff behave.

Prepaid balance requiredStarting a new extraction requires a positive organization balance. Completed jobs are metered internally and debited at your organization’s current customer rate; per-request token telemetry is not returned in extraction results.

PreviousUsage & billing NextExtractions