Extract multiple FHIR resources from text
/lang2fhir/create/multiAnalyzes natural language text and extracts multiple FHIR resources, returning them as a transaction Bundle. Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text. 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.
Patient handling. Every bundle contains exactly one Patient, and every clinical resource references it. When the text names its patient, the Patient is built from the text. When it names several patients, the Patient is the one primary_patient names, otherwise the one most of the text 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 text names its patient, the primary_patient identifier is added to that Patient unless its name, birth date, or gender contradicts the text'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 text 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.
Body parameters
Natural language text containing multiple clinical concepts to extract
FHIR version to use
Optional FHIR provider name for provider-specific profiles
Context for the patient the text is primarily about. When the text 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.
nonecheckfixFaithfulness 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.
FHIR resourceType to audit (e.g. Condition, Procedure, Observation, Encounter, MedicationRequest), matched against each generated resource's resourceType. Patient is not supported.
Field kinds to check for this resource type. Defaults to ["dates"] when omitted; use "codes" to audit clinical code concepts.
Bills the request at the lower small-note rate. When true, text must be at most 15,360 bytes (15 KiB) when UTF-8 encoded; longer text is rejected with a 400 error. Extraction behavior is the same as a standard request.
Successfully extracted FHIR resources
Response fields
Whether extraction was successful
Status message
FHIR transaction Bundle containing all extracted resources
Summary of extracted resources
Temporary UUID for the resource
FHIR resource type
Context-enriched rewritten text excerpt for this resource
Verbatim text excerpt from the original clinical document
Split classification id assigned to this resource by the /lang2fhir/document/multi endpoint. When the resource came from pages in more than one group, this is the group covering the most of its source pages, with ties going to the group with the earliest source page. Omitted when the resource came only from ungrouped pages, when its sourcePages is omitted, or for raw-text create/multi.
1-indexed source document page number(s) this resource was extracted from. Populated only by the /lang2fhir/document/multi endpoint; omitted when the source page could not be determined (e.g. raw-text create/multi, or a resource with no verbatim source text).
FHIR validation results. Present when validation_method is 'check' or 'fix'. Contains results from each validation pass. For 'check', there is one pass. For 'fix', there may be up to 3 passes as the system attempts auto-correction.
Results from each validation pass, in chronological order
Validation issues found in this pass
Validation statistics for this pass
Whether validation errors were successfully fixed by the LLM. Always false for 'check' mode. For 'fix' mode, true if errors were resolved and the returned bundle is the corrected version.
Total number of validation passes run (1 for check, 1-3 for fix)
Human-readable summary of the validation outcome
Present when the resource review ran and at least one resource was quarantined, safely remediated, or kept with an unsupported required field. The returned bundle is authoritative and contains the post-review representation of every retained resource.
Resources pulled from the bundle because an unsupported finding could not be safely repaired.
The urn:uuid of the flagged resource (its former bundle fullUrl).
The full generated FHIR resource that was pulled from the bundle.
The findings that caused the resource to be quarantined.
Resources retained in the bundle after review: unsupported codings or fields were safely removed, or unsupported required fields were kept and are reported here (see action).
The urn:uuid of the remediated resource (its bundle fullUrl).
What review did to the resource in the returned bundle: removed_codings removed unsupported codings while each affected concept kept one; removed_fields removed unsupported fields its profile does not require; flagged_required kept unsupported fields its profile requires, so the findings report values that remain in the bundle.
removed_codingsremoved_fieldsflagged_requiredFindings for fields in the pre-remediation resource that caused this action.