01

Look for a text layer first

Some PDFs look scanned and still contain a hidden text layer. Read that layer when it is there. It is faster and the same file produces the same text.

If the page is only pixels, OCR is required. DocParse treats suspected scans as a paid-workspace capability, so a trial workspace stays on deterministic parsing.

02

Keep the page with the words

A scan of a contract is useless for review if the extracted paragraph cannot be tied to a page. Store the page index with the block. Warnings belong on the job when recognition is uncertain.

Do not paste the OCR string into a prompt and drop the page list. The page is how a person checks the sentence.

03

Decide the route in the workspace

Image parsing, fast mode, high fidelity, and suspected scans are enabled for an approved paid workspace. The caller does not pick an internal model name.

After the job finishes, read the route and the warnings before you index the text. A failed or empty page should stay visible as a warning, not as a blank success.

04

What a scan does on the trial

A trial key that sets suspectedScanned or highFidelity, or that uploads an image, receives 403. The message says trial workspaces use deterministic parsing only. Those flags are how a workspace asks for the layout-aware path.

A PDF of page images uploaded without those flags can still enter the deterministic container. A page with a text layer can take the text-layer fast path, which adds the warning that the digital PDF text-layer fast path was used and skips OCR on empty pages. A page with no text may get local OCR, and the block warning says OCR fallback was used for an image-only PDF page. If that OCR returns nothing, the document warning names the page and says OCR produced no text.

  • 403 means the request asked for a paid image, Fast, or layout-aware path.
  • Read metadata.warnings before indexing a scan-like PDF.
  • OCR fallback on one page is not a clean text-layer result.
  • pageIndex 0 is the first page; the warning's page number is the 1-based file position.
05

The file to send

Upload the scanned PDF as scan.pdf. Leave fastMode, highFidelity, and suspectedScanned off the request. Setting any of them returns HTTP 403 on the trial.

Without those flags the file can enter the container. An empty page may include the block warning OCR fallback was used for an image-only PDF page. If OCR finds nothing, the warning names the page and says OCR produced no text. That page number is 1-based.

  • Read metadata.warnings before you index the text.
  • pageIndex 0 is the first page.
  • A page that still has a text layer can take the fast path and skip OCR.
export DOCPARSE_URL="https://docparse.genedai.me"
export DOCPARSE_API_KEY="your_key"

curl -fsS -X POST \
  "$DOCPARSE_URL/v1/parse?wait=true" \
  -H "Authorization: Bearer $DOCPARSE_API_KEY" \
  -F "file=@scan.pdf" \
  -F "mode=both" \
  -o result.json

jq -r '.result.markdown' result.json
jq '.result.document.schemaVersion, .result.document.pages[0].blockIds' result.json
jq '.result.manifest.decision.route, .result.manifest.parserVersion' result.json

Frequently asked questions

Questions this guide answers

Can the free trial parse a scanned PDF?

A trial workspace returns 403 for suspectedScanned, highFidelity, fastMode, and image uploads. A PDF of page images uploaded without those flags can still run on the deterministic container, and an empty page may include the OCR fallback warning.

What should a scanned-page result include?

Keep the recognized text, pageIndex, metadata.route, and the warnings. An image-only page that used local OCR says OCR fallback was used for an image-only PDF page on the block.

Should every PDF go through OCR?

A digital PDF with enough text uses the text-layer fast path and skips OCR on empty pages. The metadata warning says that fast path was used. OCR is for pages that have no usable text layer.