Extract multiple FHIR resources from a document
/lang2fhir/document/multiExtracts text from a PDF, image, RTF, or XML/C-CDA document and converts it into multiple FHIR resources, returned as a transaction Bundle. Combines document text extraction with multi-resource detection. Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types. Resources are linked with proper references (e.g., Conditions reference the Patient).
The complete JSON request body is limited to 32 MiB (33,554,432 bytes). The application enforces this whole-envelope limit, including base64-encoded document content.
Patient handling. Every bundle contains exactly one Patient, and every clinical resource references it. When the document names its patient, the Patient is built from the document. When it names several patients, the Patient is the one primary_patient names, otherwise the one most of the document is about; the others are not represented as Patients. Otherwise it is built from primary_patient when supplied, or is an unidentified Patient carrying only a synthetic identifier. When the document names its patient, the primary_patient identifier is added to that Patient unless its name, birth date, or gender contradicts the document's; the response message says whether it was added or did not match.
Patient identifier handling. US Core requires Patient.identifier (a business identifier such as an MRN). Every Patient carries a synthetic identifier with system: "urn:phenoml:lang2fhir-generated-id" and a UUID value, so the bundle remains FHIR-valid and US Core conformant. A medical record number stated in the document is added with system: "urn:phenoml:lang2fhir-document-mrn", and the primary_patient identifier is added as described above. Callers who need a tenant-specific namespace should rewrite these systems after extraction.
Page classification (optional). By default, every page with extracted text is used for extraction, and the response omits page_classifications. To classify pages so they can be grouped or dropped before extraction, set config.split_classifications. An empty list is the same as omitting it.
split_classifications is a list of up to 20 classifications that you define; there is no fixed taxonomy. Each classification has:
id: your label for the classification. Ids must be non-blank, unique, up to 64 characters, and must not be the reserved value__ungrouped__.description: a non-blank description, up to 500 characters, of the pages that belong to the classification. Each page's text is compared against these descriptions, so describe what sets those pages apart from the rest of the document.operation:groupkeeps matching pages and labels the resources extracted from them;dropremoves matching pages before extraction.
Each page is classified on its own text and assigned at most one classification. A page that does not clearly match any classification is left ungrouped. Ungrouped pages are kept, but resources extracted only from ungrouped pages are not labeled. A page that cannot be classified, for example because classification failed temporarily, is also kept and left ungrouped.
A resource's label comes from its resources[].sourcePages. When those pages include group pages, the resource carries the classification id in resources[].group and as a meta.tag with system: "https://phenoml.com/fhir/split-classification". When its source pages span more than one group, it takes the group that covers the most of them; ties go to the group with the earliest source page. Resources without sourcePages are not labeled.
The response's page_classifications reports the decision for every page, kept or dropped. When every page is dropped, the response has success: false, a message, and page_classifications, with bundle and resources set to null.
For example, the clinical and admin classifications in the request example keep and label clinical pages and drop administrative pages. To skip lab or diagnostic order forms, add a drop classification that describes them.
Body parameters
FHIR version to use
Base64 encoded file content.
Supported file types: PDF (application/pdf), PNG (image/png), JPEG (image/jpeg), TIFF (image/tiff), RTF (application/rtf), XML/C-CDA (text/xml).
TIFF, RTF, and XML/C-CDA uploads are available on dedicated instances only.
File type is auto-detected from content magic bytes.
The decoded file must not exceed 20 MiB. RTF and XML/C-CDA documents whose extracted text exceeds 1 MiB are rejected.
Generic XML must include an XML declaration; C-CDA documents rooted at ClinicalDocument may omit it.
Optional FHIR provider name for provider-specific profiles
Context for the patient the document is primarily about. When the document does not name its patient, the bundle's Patient is built from these fields. When it does, the identifier is added to that Patient unless its name, birth date, or gender contradicts these fields.
Deprecated compatibility alias for primary_patient.identifier. Cannot be combined with primary_patient.
Identifier system (namespace) for the patient identifier.
Identifier value for the patient within that system.
Implementation Guide to generate resources under. us_core (the default) and phenoml_hpo select a built-in guide. Any other value is a custom Implementation Guide name: its profiles are included alongside the US Core profiles, which are always the base layer. A custom name that matches no uploaded Implementation Guide returns 404.
Deprecated and ignored: both values produce the same result. This field will be removed in a future release.
standarddeepFHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips.
nonecheckfixOptional processing configuration shared across document endpoints.
Optional per-page classifications, applied before extraction; accepts up to 20 classifications. When omitted or empty, every page with extracted text is used. This is a caller-defined list, not a fixed taxonomy: choose each classification id and describe the pages that belong to it. Each page is assigned at most one classification; a page that does not clearly match any, or that cannot be classified, is kept and left ungrouped. Pages matching a drop classification are removed before extraction. Pages matching a group classification are kept; on /lang2fhir/document/multi, resources extracted from them include the classification id in resources[].group and as a FHIR meta.tag. When every page is dropped, /lang2fhir/document returns 422 and /lang2fhir/document/multi returns success false with page_classifications. Example ids such as clinical and admin are illustrative, not a fixed set.
Unique, non-blank classification id. Returned as page_classifications[].classification_id and, for group classifications, as resources[].group and the FHIR meta.tag code. The reserved id "ungrouped" is not allowed.
Non-blank natural-language description of the pages that belong to this classification. Each page's text is compared against these descriptions, so describe what distinguishes these pages from the rest of the document.
Operation applied to pages assigned this classification. group keeps the pages and labels resources extracted from them with this id. drop removes the pages before extraction.
groupdropFaithfulness audit of the generated resources (honored by /lang2fhir/create/multi and /lang2fhir/document/multi). When resource_review is omitted, the audit runs with these default targets: Encounter checks dates; Procedure and DiagnosticReport check dates and codes; Observation, Condition, and MedicationRequest check codes. Supplying resource_review replaces the defaults with the listed targets; an empty targets list turns the audit off. For each selected resource type an LLM checks whether selected dates and clinical code concepts are actually supported by the full source document. An unsupported individual coding is removed when another coding remains in its concept. Resources with an unsupported structural field, a profile-required coding, or no coding remaining in an affected concept, are pulled out of the returned bundle and reported under resource_review in the response. Encounters, and diagnostic reports built from the source's report dates, are never pulled out, because other resources in the bundle reference them: an unsupported field is removed from them when their profile does not require it, and kept and reported when it does.
The resource types to audit and which date or clinical code field kinds to check. An empty list turns the audit off.
Successfully extracted FHIR resources from document
Response fields