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

implementation_guidestringoptional

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

detection_effortstringoptionaldefault standard

Detection effort. '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

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

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

POSTRequest

curl -X POST 'https://experiment.app.pheno.ml/lang2fhir/create/multi' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -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 OKResponse

{
  "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"
        }
      }
    ]
  }
}