Documents & extraction

Uploading

curl -X POST https://api.sandbox.railflo.com/v1/documents \
  -H "Authorization: Bearer railflo_sk_test_..." \
  -F file=@referral.pdf

Accepts PDF, DOCX, and common scanned-image formats, up to 25 MB (multipart) or 6 MB (JSON + base64). The response returns immediately with status: "processing" — a document is never held for the async pipeline to finish before you get an id back.

Pipeline stages

1. Quarantine write — the file is stored, hashed, and content-deduplicated before anything else touches it. Uploading the same bytes twice returns the same document, not a duplicate.
2. Virus scan — a real ClamAV scan against a current signature database. An infected file is rejected outright; it never reaches any later stage.
3. Format normalisation — converted to a canonical PDF rendition (DOCX and scanned images go through a real conversion/OCR pipeline, not a placeholder).
4. Text extraction — born-digital PDFs get their embedded text layer; scanned pages are OCR’d.
5. Classification — determines the document kind (referral, letter, result, discharge, or admin/unknown) and a confidence score.
6. Patient linking — matches the document to a patient record by identifier (auto-links) or by name+DOB (proposes a match for a human to confirm — never auto-links on demographics alone).
7. Promotion — a classified, linked document gets a real FHIR DocumentReference created in your clinical store.

Status and confidence

Status	Meaning
processing	Still moving through the pipeline.
ready	Classified with high confidence, patient-linked, promoted.
needs_review	Low classification confidence, or a proposed (not confirmed) patient match — a human needs to look at it.
rejected	Failed virus scan, or an unsupported format.

Confidence is a real, reproducible property of the classification run — every classification records which model/prompt version produced it, so a later re-run’s result is always traceable to what generated it (a regulatory posture, not a nicety).

The review queue

Anything landing in needs_review shows up in Console’s review queue. A reviewer works through each document field-by-field: accept, edit, or reject, with the source document and evidence highlighting shown side by side. Nothing AI-extracted becomes part of the clinical record without a human accepting it — this is a hard rule, not a configurable setting.

Accepting a referral, result, or discharge document (or anything unclassified) additionally requires a CLINICIAN or OWNER role — a SECRETARY can review and stage corrections, but can’t be the final sign-off on clinical content.

Retrieving

curl https://api.sandbox.railflo.com/v1/documents/{id} \
  -H "Authorization: Bearer railflo_sk_test_..."

Returns the document’s current status, classification (kind + confidence), and — once linked — the patient it’s attached to.