Extract multiple FHIR resources from text

POST/lang2fhir/create/multi

Analyzes 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).

Patient identifier handling. US Core requires Patient.identifier (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with system: "urn:phenoml:lang2fhir-generated-id" and a UUID value so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.

RequiresBearerauthentication

Body parameters

textstringrequired

Natural language text containing multiple clinical concepts to extract

versionstringoptionaldefault R4

FHIR version to use

providerstringoptional

Optional FHIR provider name for provider-specific profiles

primary_patientobjectoptional

Partial context for the patient the document is primarily about. This is not a complete FHIR Patient resource. Lang2FHIR uses the available context to identify a generated primary Patient reliably. An identifier supplied here is added to that Patient; when no Patient is generated, it is used in logical references on generated clinical resources.

identifierobjectoptional

Business identifier for the document's primary patient. When Lang2FHIR identifies that Patient in generated output, it adds this identifier to the Patient's identifier list (preserving existing identifiers). If no Patient is generated, Lang2FHIR uses it in logical references on generated clinical resources. Supply the patient-level identifier (not an order or specimen identifier).

systemstringrequired

Identifier system (namespace) for the patient identifier.

valuestringrequired

Identifier value for the patient within that system.

nameobjectoptional

The known portions of the primary patient's name. Provide a non-empty family name or at least one non-empty given name.

familystringoptional

Family name.

givenstring[]optional

Given names. Matching succeeds when a generated name has a supplied given name.

birthDatestring (date)optional

Complete date of birth in YYYY-MM-DD format.

genderstringoptional

Administrative gender. This corroborates another match but does not identify a patient alone.

malefemaleotherunknown

patient_referenceobjectoptional

systemstringrequired

Identifier system (namespace) for the patient identifier.

valuestringrequired

Identifier value for the patient within that system.

implementation_guidestringoptional

Custom Implementation Guide name. When specified, profiles from this IG are included alongside the default profiles during resource detection. Default profiles are always the base layer; custom IG profiles are additive.

detection_effortstringoptionaldefault standard

Deprecated; use the default 'standard' value. This field will be removed in a future release. 'standard' runs detection once; 'deep' runs detection multiple times for higher recall.

standarddeep

validation_methodstringoptionaldefault none

FHIR 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.

nonecheckfix

resource_reviewobjectoptional

Opt-in faithfulness audit (honored by /lang2fhir/create/multi and /lang2fhir/document/multi). 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.

targetsobject[]required

The resource types to audit and which date or clinical code field kinds to check.

resource_typestringrequired

FHIR resourceType to audit (e.g. Condition, Procedure, Observation, Encounter, MedicationRequest), matched against each generated resource's resourceType. Patient is not supported.

fieldsstring[]optional

Field kinds to check for this resource type. Defaults to ["dates"] when omitted; use "codes" to audit clinical code concepts.

Returns

Successfully extracted FHIR resources

Response fields

successbooleanoptional

Whether extraction was successful

messagestringoptional

Status message

bundleobjectoptional

FHIR transaction Bundle containing all extracted resources

resourceTypestringoptional

typestringoptional

entryobject[]optional

fullUrlstringoptional

resourceobjectoptional

requestobjectoptional

resourcesobject[]optional

Summary of extracted resources

tempIdstringoptional

Temporary UUID for the resource

resourceTypestringoptional

FHIR resource type

descriptionstringoptional

Context-enriched rewritten text excerpt for this resource

originalTextstringoptional

Verbatim text excerpt from the original clinical document

groupstringoptional

Split classification id assigned to this resource by the /lang2fhir/document/multi endpoint. Omitted when the resource came only from ungrouped pages or raw-text create/multi.

sourcePagesinteger[]optional

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).

validationobjectoptional

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.

passesobject[]optional

Results from each validation pass, in chronological order

issuesobject[]optional

Validation issues found in this pass

statsobjectoptional

Validation statistics for this pass

fixedbooleanoptional

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.

attemptsintegeroptional

Total number of validation passes run (1 for check, 1-3 for fix)

summarystringoptional

Human-readable summary of the validation outcome

resource_reviewobjectoptional

Present when resource_review was requested and at least one resource was quarantined or safely remediated. The returned bundle is authoritative and contains the post-review representation of every retained resource.

flaggedobject[]optional

Resources pulled from the bundle because an unsupported finding could not be safely repaired.

tempIdstringoptional

The urn:uuid of the flagged resource (its former bundle fullUrl).

resourceTypestringoptional

resourceobjectoptional

The full generated FHIR resource that was pulled from the bundle.

findingsobject[]optional

The findings that caused the resource to be quarantined.

remediatedobject[]optional

Resources retained in the bundle after unsupported codings were safely removed.

tempIdstringoptional

The urn:uuid of the remediated resource (its bundle fullUrl).

resourceTypestringoptional

actionstringoptional

The safe change applied to the resource in the returned bundle.

removed_codings

findingsobject[]optional

Findings for fields in the pre-remediation resource that caused this action.

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/lang2fhir/create/multi" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "John Smith, 45-year-old male, diagnosed with Type 2 Diabetes. Prescribed Metformin 500mg twice daily. Blood pressure 140/90.",
  "version": "R4"
}'

200 OKExample Response

{
  "success": true,
  "message": "Successfully extracted 3 resources",
  "bundle": {
    "resourceType": "Bundle",
    "type": "transaction",
    "entry": [
      {
        "fullUrl": "urn:uuid:patient-001",
        "resource": {
          "resourceType": "Patient",
          "name": [
            {
              "given": [
                "John"
              ],
              "family": "Smith"
            }
          ],
          "gender": "male"
        },
        "request": {
          "method": "POST",
          "url": "Patient"
        }
      },
      {
        "fullUrl": "urn:uuid:condition-001",
        "resource": {
          "resourceType": "Condition",
          "code": {
            "text": "Type 2 Diabetes"
          }
        },
        "request": {
          "method": "POST",
          "url": "Condition"
        }
      },
      {
        "fullUrl": "urn:uuid:medication-001",
        "resource": {
          "resourceType": "MedicationRequest",
          "medicationCodeableConcept": {
            "text": "Metformin 500mg"
          }
        },
        "request": {
          "method": "POST",
          "url": "MedicationRequest"
        }
      }
    ]
  }
}