Convert document to FHIR resource

POST/lang2fhir/document

Extracts text from a PDF, image, RTF, or XML/C-CDA document and converts it into a structured FHIR resource.

Patient identifier handling. When generating a patient (or patient-canvas) resource, 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 resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.

RequiresBearerauthentication

Body parameters

versionstringrequired

FHIR version to use

resourcestringrequired

Type of FHIR resource to create. Accepts any FHIR resource type or US Core profile name.

contentstringrequired

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.

configobjectoptional

Optional processing configuration shared across document endpoints.

page_filterobjectoptional

Deprecated. Use split_classifications instead.

split_classificationsobject[]optional

Optional per-page split classifications. Mutually exclusive with page_filter. This is a caller-defined list, not a fixed taxonomy: choose each classification id and write a natural-language description for the per-page classifier. For each page, the classifier assigns the best-matching classification or leaves the page ungrouped. Pages matching operation=drop are removed before extraction. Pages matching operation=group are kept, and extracted resources attributed to those pages include the classification id in response metadata and FHIR meta.tag. Example ids such as clinical and admin are illustrative, not a fixed set.

idstringrequired

Unique classification id. The reserved id "ungrouped" is not allowed.

descriptionstringrequired

Natural-language description of pages that belong to this classification.

operationstringrequired

Operation applied to pages assigned this classification.

groupdrop

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.

Returns

Successfully created FHIR resource from document

Response fields

resourceTypestringoptional

statusstringoptional

titlestringoptional

itemarray<object>optional

linkIdstringoptional

textstringoptional

typestringoptional

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/document" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "version": "R4",
  "resource": "questionnaire",
  "content": "JVBERi0xLjQKJeLjz9MK...(base64-encoded document bytes)"
}'

200 OKExample Response

{
  "resourceType": "Questionnaire",
  "status": "active",
  "title": "Patient Intake Form",
  "item": [
    {
      "linkId": "1",
      "text": "What is your name?",
      "type": "string"
    },
    {
      "linkId": "2",
      "text": "What is your date of birth?",
      "type": "date"
    }
  ]
}