Map FHIR resources to OMOP CDM v5.4

POST/fhir2omop/create

Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows (person, visit_occurrence, condition_occurrence, drug_exposure, procedure_occurrence, measurement, observation).

Resource support is intentionally limited to the OMOP tables returned by this endpoint:

Patient -> person
Encounter -> visit_occurrence
Condition -> condition_occurrence
Procedure -> procedure_occurrence
MedicationRequest, MedicationStatement, and MedicationAdministration -> drug_exposure
Immunization -> drug_exposure
Observation with a numeric valueQuantity, valueInteger, or numeric-looking valueString (for example "<2") -> measurement
non-numeric Observation -> observation
AllergyIntolerance -> observation

Medication is supported only as reference data for medication resources; it is not emitted as its own row because OMOP CDM has no Medication table. Other reference/admin resources such as Practitioner, Organization, Location, Coverage, and Claim, and clinical workflow/document resources such as DiagnosticReport, ServiceRequest, CarePlan, DocumentReference, Composition, Specimen, and DeviceUseStatement, are currently accepted in a Bundle but are not shaped into OMOP rows. Unsupported resource types are ignored rather than listed under dropped; dropped is reserved for supported resource types that were missing the subject/patient, code, or medication reference data needed to produce a valid row.

Each resource's primary clinical coding is resolved to a standard OMOP concept_id. Alongside the OMOP rows grouped by table (tables), the response carries mappings (how each source coding resolved, linked back to the row it produced), dropped (resources that could not be shaped into a row), vocab_version (the OMOP vocabulary release codes were resolved against), and a small summary of the resolution outcomes.

A concept_id of 0 is reported, not omitted (OMOP "no matching concept" semantics): it covers both a coding with no standard match (UNMAPPED) and an unverified suggestion for a text-only resource (UNCHECKED). Only the primary clinical coding is resolved, so gender/race/ethnicity/visit/value/unit concept_ids are always 0; the one populated non-resolved concept is measurement operator_concept_id, set from a value comparator (<, <=, >, >=) rather than the resolver. Each *_source_value carries the verbatim FHIR coding (system#code), and *_type_concept_id is set to 32817 (EHR).

Medication codes are resolved whether they appear inline (medicationCodeableConcept) or via a medicationReference to a contained, relative (Type/id), or bundle-entry (urn:uuid) Medication resource. Resources that cannot be shaped into a row — a medication with no usable code, resolvable reference, or display, or any clinical resource whose subject/patient reference cannot be tied to a person — are reported under dropped rather than emitted as blank rows. The bundle must contain at least one Patient resource.

RequiresBearerauthentication

Body parameters

fhir_resourcesobjectrequired

FHIR resources (single resource or Bundle). Must contain at least one Patient resource. Supported row-producing resources are Patient, Encounter, Condition, Procedure, MedicationRequest, MedicationStatement, MedicationAdministration, Immunization, Observation, and AllergyIntolerance. Standalone Medication resources are consumed by medication references rather than mapped to their own table. Other resource types are accepted but ignored.

Returns

FHIR resources mapped to OMOP CDM v5.4

Response fields

successbooleanoptional

messagestringoptional

tablesobjectoptional

OMOP CDM v5.4 rows grouped by destination table.

locationobject[]optional

location_idinteger (int64)optional

address_1stringoptional

address_2stringoptional

citystringoptional

statestringoptional

zipstringoptional

countystringoptional

location_source_valuestringoptional

country_concept_idinteger (int64)optional

country_source_valuestringoptional

latitudenumber (double)optional

longitudenumber (double)optional

care_siteobject[]optional

care_site_idinteger (int64)optional

care_site_namestringoptional

place_of_service_concept_idinteger (int64)optional

location_idinteger (int64)optional

care_site_source_valuestringoptional

place_of_service_source_valuestringoptional

providerobject[]optional

provider_idinteger (int64)optional

provider_namestringoptional

npistringoptional

deastringoptional

specialty_concept_idinteger (int64)optional

care_site_idinteger (int64)optional

year_of_birthintegeroptional

gender_concept_idinteger (int64)optional

provider_source_valuestringoptional

specialty_source_valuestringoptional

specialty_source_concept_idinteger (int64)optional

gender_source_valuestringoptional

gender_source_concept_idinteger (int64)optional

personobject[]optional

person_idinteger (int64)optional

gender_concept_idinteger (int64)optional

year_of_birthintegeroptional

month_of_birthintegeroptional

day_of_birthintegeroptional

birth_datetimestringoptional

race_concept_idinteger (int64)optional

ethnicity_concept_idinteger (int64)optional

location_idinteger (int64)optional

person_source_valuestringoptional

gender_source_valuestringoptional

race_source_valuestringoptional

ethnicity_source_valuestringoptional

deathobject[]optional

person_idinteger (int64)optional

death_datestringoptional

death_datetimestringoptional

death_type_concept_idinteger (int64)optional

cause_concept_idinteger (int64)optional

cause_source_valuestringoptional

cause_source_concept_idinteger (int64)optional

observation_periodobject[]optional

observation_period_idinteger (int64)optional

person_idinteger (int64)optional

observation_period_start_datestringoptional

observation_period_end_datestringoptional

period_type_concept_idinteger (int64)optional

visit_occurrenceobject[]optional

visit_occurrence_idinteger (int64)optional

person_idinteger (int64)optional

visit_concept_idinteger (int64)optional

visit_start_datestringoptional

visit_start_datetimestringoptional

visit_end_datestringoptional

visit_end_datetimestringoptional

visit_type_concept_idinteger (int64)optional

provider_idinteger (int64)optional

care_site_idinteger (int64)optional

visit_source_valuestringoptional

condition_occurrenceobject[]optional

condition_occurrence_idinteger (int64)optional

person_idinteger (int64)optional

condition_concept_idinteger (int64)optional

condition_start_datestringoptional

condition_start_datetimestringoptional

condition_end_datestringoptional

condition_type_concept_idinteger (int64)optional

visit_occurrence_idinteger (int64)optional

provider_idinteger (int64)optional

condition_source_valuestringoptional

condition_source_concept_idinteger (int64)optional

condition_status_source_valuestringoptional

drug_exposureobject[]optional

drug_exposure_idinteger (int64)optional

person_idinteger (int64)optional

drug_concept_idinteger (int64)optional

drug_exposure_start_datestringoptional

drug_exposure_start_datetimestringoptional

drug_exposure_end_datestringoptional

drug_type_concept_idinteger (int64)optional

stop_reasonstringoptional

sigstringoptional

visit_occurrence_idinteger (int64)optional

provider_idinteger (int64)optional

drug_source_valuestringoptional

drug_source_concept_idinteger (int64)optional

procedure_occurrenceobject[]optional

procedure_occurrence_idinteger (int64)optional

person_idinteger (int64)optional

procedure_concept_idinteger (int64)optional

procedure_datestringoptional

procedure_datetimestringoptional

procedure_type_concept_idinteger (int64)optional

visit_occurrence_idinteger (int64)optional

provider_idinteger (int64)optional

procedure_source_valuestringoptional

procedure_source_concept_idinteger (int64)optional

measurementobject[]optional

measurement_idinteger (int64)optional

person_idinteger (int64)optional

measurement_concept_idinteger (int64)optional

measurement_datestringoptional

measurement_datetimestringoptional

measurement_type_concept_idinteger (int64)optional

value_as_numbernumber (double)optional

operator_concept_idinteger (int64)optional

OMOP "Meas Value Operator" standard concept qualifying value_as_number (<, <=, >, >=), parsed from a numeric-string value or a FHIR valueQuantity.comparator. 0 when no operator (a bare number).

value_as_concept_idinteger (int64)optional

unit_concept_idinteger (int64)optional

range_lownumber (double)optional

range_highnumber (double)optional

visit_occurrence_idinteger (int64)optional

provider_idinteger (int64)optional

measurement_source_valuestringoptional

measurement_source_concept_idinteger (int64)optional

unit_source_valuestringoptional

value_source_valuestringoptional

observationobject[]optional

observation_idinteger (int64)optional

person_idinteger (int64)optional

observation_concept_idinteger (int64)optional

observation_datestringoptional

observation_datetimestringoptional

observation_type_concept_idinteger (int64)optional

value_as_numbernumber (double)optional

value_as_stringstringoptional

value_as_concept_idinteger (int64)optional

unit_concept_idinteger (int64)optional

visit_occurrence_idinteger (int64)optional

provider_idinteger (int64)optional

observation_source_valuestringoptional

observation_source_concept_idinteger (int64)optional

unit_source_valuestringoptional

value_source_valuestringoptional

mappingsobject[]optional

One entry per source coding (or one entry for a text-only resource with no coding), describing how it resolved and linking back to the row it produced.

resource_typestringoptional

resource_idstringoptional

omop_tablestringoptional

omop_idinteger (int64)optional

The id of the OMOP row this coding produced (e.g. condition_occurrence_id), within omop_table. A resource with multiple codings yields one entry per coding, all sharing this id.

source_systemstringoptional

source_codestringoptional

source_namestringoptional

target_vocabularystringoptional

target_codestringoptional

The standard concept's own code: the source code itself for an ALREADY_STANDARD row, the standard concept's code for a MAPPED row, or the suggested code for an UNCHECKED row. Omitted for UNMAPPED rows.

target_namestringoptional

mapping_statusstringoptional

ALREADY_STANDARD (source coding is already a standard OMOP concept), MAPPED (source coding was mapped to a standard concept), UNCHECKED (a standard code was suggested — e.g. for a text-only resource — but not verified against the OMOP vocabulary, so concept_id stays 0), or UNMAPPED (no standard concept found).

notestringoptional

droppedobject[]optional

Supported resource instances that could not be shaped into an OMOP row because required subject/patient, code, or medication reference data was missing. Unsupported resource types are ignored and do not appear here.

resource_typestringoptional

resource_idstringoptional

reasonstringoptional

vocab_versionstringoptional

The OMOP vocabulary release the clinical codes were resolved against (e.g. "v20240229"), for reproducibility. Present when at least one coded concept was resolved.

summaryobjectoptional

The request's data-quality headline: how the coded concepts split across resolution outcomes, and the share that was not already in a target standard vocabulary. Each coded resource is counted once (per resolved concept), even when it carried several codings — unlike mappings, which has one entry per coding.

codes_already_standardintegeroptional

Coded concepts already a standard OMOP concept (ALREADY_STANDARD).

codes_normalizedintegeroptional

Coded concepts mapped or suggested to a standard concept (MAPPED or UNCHECKED).

codes_unmappedintegeroptional

Coded concepts with no standard concept found (UNMAPPED).

off_vocab_ratenumber (double)optional

Share of coded concepts not already standard ((normalized + unmapped) / total).

POSTRequest

curl -X POST 'https://experiment.app.pheno.ml/fhir2omop/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "fhir_resources": {
    "resourceType": "Bundle",
    "type": "collection",
    "entry": [
      {
        "resource": {
          "resourceType": "Patient",
          "id": "patient-1",
          "gender": "female",
          "birthDate": "1985-07-22"
        }
      },
      {
        "resource": {
          "resourceType": "Condition",
          "id": "condition-1",
          "subject": {
            "reference": "Patient/patient-1"
          },
          "code": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "44054006",
                "display": "Type 2 diabetes mellitus"
              }
            ]
          },
          "onsetDateTime": "2024-01-15"
        }
      },
      {
        "resource": {
          "resourceType": "MedicationRequest",
          "id": "medreq-1",
          "status": "active",
          "subject": {
            "reference": "Patient/patient-1"
          },
          "medicationReference": {
            "reference": "#med0"
          },
          "authoredOn": "2024-01-16",
          "contained": [
            {
              "resourceType": "Medication",
              "id": "med0",
              "code": {
                "coding": [
                  {
                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                    "code": "860975",
                    "display": "metformin hydrochloride 500 MG"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}'

200 OKResponse

{
  "success": true,
  "message": "Operation completed successfully",
  "tables": {
    "location": [
      {
        "location_id": 10,
        "address_1": "123 Main St",
        "address_2": "123 Main St",
        "city": "San Francisco",
        "state": "example",
        "zip": "example",
        "county": "example",
        "location_source_value": "example",
        "country_concept_id": 10,
        "country_source_value": "US",
        "latitude": 0.5,
        "longitude": 0.5
      }
    ],
    "care_site": [
      {
        "care_site_id": 10,
        "care_site_name": "Example Name",
        "place_of_service_concept_id": 10,
        "location_id": 10,
        "care_site_source_value": "example",
        "place_of_service_source_value": "example"
      }
    ],
    "provider": [
      {
        "provider_id": 10,
        "provider_name": "Example Name",
        "npi": "example",
        "dea": "example",
        "specialty_concept_id": 10,
        "care_site_id": 10,
        "year_of_birth": 10,
        "gender_concept_id": 10,
        "provider_source_value": "example",
        "specialty_source_value": "example",
        "specialty_source_concept_id": 10,
        "gender_source_value": "example",
        "gender_source_concept_id": 10
      }
    ],
    "person": [
      {
        "person_id": 10,
        "gender_concept_id": 10,
        "year_of_birth": 10,
        "month_of_birth": 10,
        "day_of_birth": 10,
        "birth_datetime": "example",
        "race_concept_id": 10,
        "ethnicity_concept_id": 10,
        "location_id": 10,
        "person_source_value": "example",
        "gender_source_value": "example",
        "race_source_value": "example",
        "ethnicity_source_value": "San Francisco"
      }
    ],
    "death": [
      {
        "person_id": 10,
        "death_date": "example",
        "death_datetime": "example",
        "death_type_concept_id": 10,
        "cause_concept_id": 10,
        "cause_source_value": "example",
        "cause_source_concept_id": 10
      }
    ],
    "observation_period": [
      {
        "observation_period_id": 10,
        "person_id": 10,
        "observation_period_start_date": "example",
        "observation_period_end_date": "example",
        "period_type_concept_id": 10
      }
    ],
    "visit_occurrence": [
      {
        "visit_occurrence_id": 10,
        "person_id": 10,
        "visit_concept_id": 10,
        "visit_start_date": "example",
        "visit_start_datetime": "example",
        "visit_end_date": "example",
        "visit_end_datetime": "example",
        "visit_type_concept_id": 10,
        "provider_id": 10,
        "care_site_id": 10,
        "visit_source_value": "example"
      }
    ],
    "condition_occurrence": [
      {
        "condition_occurrence_id": 10,
        "person_id": 10,
        "condition_concept_id": 10,
        "condition_start_date": "example",
        "condition_start_datetime": "example",
        "condition_end_date": "example",
        "condition_type_concept_id": 10,
        "visit_occurrence_id": 10,
        "provider_id": 10,
        "condition_source_value": "example",
        "condition_source_concept_id": 10,
        "condition_status_source_value": "active"
      }
    ],
    "drug_exposure": [
      {
        "drug_exposure_id": 10,
        "person_id": 10,
        "drug_concept_id": 10,
        "drug_exposure_start_date": "example",
        "drug_exposure_start_datetime": "example",
        "drug_exposure_end_date": "example",
        "drug_type_concept_id": 10,
        "stop_reason": "example",
        "sig": "example",
        "visit_occurrence_id": 10,
        "provider_id": 10,
        "drug_source_value": "example",
        "drug_source_concept_id": 10
      }
    ],
    "procedure_occurrence": [
      {
        "procedure_occurrence_id": 10,
        "person_id": 10,
        "procedure_concept_id": 10,
        "procedure_date": "example",
        "procedure_datetime": "example",
        "procedure_type_concept_id": 10,
        "visit_occurrence_id": 10,
        "provider_id": 10,
        "procedure_source_value": "example",
        "procedure_source_concept_id": 10
      }
    ],
    "measurement": [
      {
        "measurement_id": 10,
        "person_id": 10,
        "measurement_concept_id": 10,
        "measurement_date": "example",
        "measurement_datetime": "example",
        "measurement_type_concept_id": 10,
        "value_as_number": 0.5,
        "operator_concept_id": 10,
        "value_as_concept_id": 10,
        "unit_concept_id": 10,
        "range_low": 0.5,
        "range_high": 0.5,
        "visit_occurrence_id": 10,
        "provider_id": 10,
        "measurement_source_value": "example",
        "measurement_source_concept_id": 10,
        "unit_source_value": "example",
        "value_source_value": "example"
      }
    ],
    "observation": [
      {
        "observation_id": 10,
        "person_id": 10,
        "observation_concept_id": 10,
        "observation_date": "example",
        "observation_datetime": "example",
        "observation_type_concept_id": 10,
        "value_as_number": 0.5,
        "value_as_string": "example",
        "value_as_concept_id": 10,
        "unit_concept_id": 10,
        "visit_occurrence_id": 10,
        "provider_id": 10,
        "observation_source_value": "example",
        "observation_source_concept_id": 10,
        "unit_source_value": "example",
        "value_source_value": "example"
      }
    ]
  },
  "mappings": [
    {
      "resource_type": "Patient",
      "resource_id": "abc-123-def-456",
      "omop_table": "example",
      "omop_id": 10,
      "source_system": "example",
      "source_code": "ABC123",
      "source_name": "Example Name",
      "target_vocabulary": "example",
      "target_code": "ABC123",
      "target_name": "Example Name",
      "mapping_status": "active",
      "note": "example"
    }
  ],
  "dropped": [
    {
      "resource_type": "Patient",
      "resource_id": "abc-123-def-456",
      "reason": "example"
    }
  ],
  "vocab_version": "example",
  "summary": {
    "codes_already_standard": 10,
    "codes_normalized": 10,
    "codes_unmapped": 10,
    "off_vocab_rate": 0.5
  }
}