FHIR R4 Integration

Interoperability

PearMedica's primary API uses a proprietary JSON format for speed and simplicity. For teams that need EMR/EHR interoperability, we offer dedicated FHIR R4 endpoints as an optional translation layer over the same assessment engine.

HL7 FHIR R4

SNOMED CT · ICD-10 · LOINC

Bearer Auth

FHIR Endpoints

These endpoints wrap the same assessment pipeline as the proprietary /api/v1/assess endpoint, but accept and return HL7 FHIR R4 resources. Use them when integrating with FHIR-aware platforms.

POST

/api/v1/fhir/assess

Submit a FHIR Bundle containing Patient + Observation resources. Returns a FHIR Bundle with DiagnosticReport, Condition, and DetectedIssue resources.

Auth: Bearer token (same API key as proprietary endpoint)

Content-Type: application/fhir+json

GET

/api/v1/fhir/metadata

FHIR CapabilityStatement — machine-readable declaration of supported resources, interactions, and security. No authentication required.

Auth: None (public per FHIR spec)

Content-Type: application/fhir+json

FHIR Request Example

When using the FHIR endpoint, send a FHIR Bundle with a Patient resource and one or more Observation resources (symptoms/evidence):

json

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "gender": "female",
        "birthDate": "1991",
        "address": [{
          "text": "lagos_nigeria",
          "extension": [{
            "url": "http://hl7.org/fhir/StructureDefinition/geolocation",
            "extension": [
              { "url": "latitude", "valueDecimal": 6.5244 },
              { "url": "longitude", "valueDecimal": 3.3792 }
            ]
          }]
        }]
      }
    },
    {
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "code": {
          "coding": [{
            "system": "https://pearmedica.com/fhir/CodeSystem/pearmedica",
            "code": "s_fever",
            "display": "Fever"
          }]
        },
        "interpretation": [{
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
            "code": "POS",
            "display": "Positive"
          }]
        }],
        "component": [
          {
            "code": { "coding": [{ "system": "http://snomed.info/sct", "code": "246112005", "display": "Severity" }] },
            "valueCodeableConcept": { "coding": [{ "system": "http://snomed.info/sct", "code": "6736007", "display": "Moderate" }] }
          },
          {
            "code": { "coding": [{ "system": "http://snomed.info/sct", "code": "103335007", "display": "Duration" }] },
            "valueQuantity": { "value": 3, "unit": "d", "system": "http://unitsofmeasure.org", "code": "d" }
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "code": {
          "coding": [{
            "system": "https://pearmedica.com/fhir/CodeSystem/pearmedica",
            "code": "s_headache",
            "display": "Headache"
          }]
        },
        "interpretation": [{
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
            "code": "POS"
          }]
        }]
      }
    }
  ]
}

FHIR Response Example

The FHIR endpoint translates the assessment result into a standards-compliant FHIR Bundle containing a DiagnosticReport with triage information, and Condition resources with ICD-10 coding and probability scores:

json

{
  "resourceType": "Bundle",
  "type": "collection",
  "total": 6,
  "entry": [
    {
      "resource": {
        "resourceType": "DiagnosticReport",
        "status": "final",
        "code": {
          "text": "AI-Powered Clinical Assessment"
        },
        "extension": [
          {
            "url": "https://pearmedica.com/fhir/Extension/triage-level",
            "valueCodeableConcept": {
              "coding": [{
                "system": "https://pearmedica.com/fhir/CodeSystem/triage-level",
                "code": "urgent",
                "display": "Urgent — Medical attention within hours"
              }]
            }
          },
          {
            "url": "https://pearmedica.com/fhir/Extension/assessment-confidence",
            "valueDecimal": 0.87
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Condition",
        "code": {
          "coding": [
            { "system": "https://pearmedica.com/fhir/CodeSystem/pearmedica", "code": "c_malaria", "display": "Plasmodium falciparum Malaria" },
            { "system": "http://hl7.org/fhir/sid/icd-10", "code": "B50.9", "display": "Plasmodium falciparum Malaria" }
          ],
          "text": "Malaria"
        },
        "severity": {
          "coding": [{ "system": "http://snomed.info/sct", "code": "6736007", "display": "Moderate" }]
        },
        "extension": [{
          "url": "https://pearmedica.com/fhir/Extension/condition-probability",
          "valueDecimal": 0.78
        }]
      }
    }
  ]
}

Terminology Systems

When using the FHIR endpoints, PearMedica maps clinical concepts to the following standard terminology systems. These codes appear in FHIR resources only — the proprietary API uses PearMedica's own identifiers.

System	URI	Used For
SNOMED CT	http://snomed.info/sct	Symptoms, severity, clinical findings
ICD-10	http://hl7.org/fhir/sid/icd-10	Assessed conditions (diagnosis codes)
LOINC	http://loinc.org	Lab tests, vitals, observations
PearMedica Local	https://pearmedica.com/fhir/CodeSystem/pearmedica	Local symptom/condition IDs without standard binding

Switching to FHIR from the Proprietary API

Already integrated with the proprietary /api/v1/assess endpoint? You can optionally add FHIR support alongside it, or migrate entirely — both endpoints run the same assessment engine under the hood:

Same auth — use the same API key and Bearer token header
Wrap your patient data in a FHIR Patient resource (gender + birthDate)
Wrap each symptom in a FHIR Observation resource (code + interpretation)
Bundle them into a FHIR Bundle (type: "collection")
POST to /api/v1/fhir/assess instead of /api/v1/assess
Parse the response as a FHIR Bundle containing DiagnosticReport + Condition resources

Full API Reference Get Started

Loading documentation…

Code Examples Integration Patterns

FHIR Endpoints

These endpoints wrap the same assessment pipeline as the proprietary /api/v1/assess endpoint, but accept and return HL7 FHIR R4 resources. Use them when integrating with FHIR-aware platforms.

POST

/api/v1/fhir/assess

Submit a FHIR Bundle containing Patient + Observation resources. Returns a FHIR Bundle with DiagnosticReport, Condition, and DetectedIssue resources.

Auth: Bearer token (same API key as proprietary endpoint)

Content-Type: application/fhir+json

GET

/api/v1/fhir/metadata

FHIR CapabilityStatement — machine-readable declaration of supported resources, interactions, and security. No authentication required.

Auth: None (public per FHIR spec)

Content-Type: application/fhir+json

FHIR Request Example

When using the FHIR endpoint, send a FHIR Bundle with a Patient resource and one or more Observation resources (symptoms/evidence):

json

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "gender": "female",
        "birthDate": "1991",
        "address": [{
          "text": "lagos_nigeria",
          "extension": [{
            "url": "http://hl7.org/fhir/StructureDefinition/geolocation",
            "extension": [
              { "url": "latitude", "valueDecimal": 6.5244 },
              { "url": "longitude", "valueDecimal": 3.3792 }
            ]
          }]
        }]
      }
    },
    {
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "code": {
          "coding": [{
            "system": "https://pearmedica.com/fhir/CodeSystem/pearmedica",
            "code": "s_fever",
            "display": "Fever"
          }]
        },
        "interpretation": [{
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
            "code": "POS",
            "display": "Positive"
          }]
        }],
        "component": [
          {
            "code": { "coding": [{ "system": "http://snomed.info/sct", "code": "246112005", "display": "Severity" }] },
            "valueCodeableConcept": { "coding": [{ "system": "http://snomed.info/sct", "code": "6736007", "display": "Moderate" }] }
          },
          {
            "code": { "coding": [{ "system": "http://snomed.info/sct", "code": "103335007", "display": "Duration" }] },
            "valueQuantity": { "value": 3, "unit": "d", "system": "http://unitsofmeasure.org", "code": "d" }
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "code": {
          "coding": [{
            "system": "https://pearmedica.com/fhir/CodeSystem/pearmedica",
            "code": "s_headache",
            "display": "Headache"
          }]
        },
        "interpretation": [{
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
            "code": "POS"
          }]
        }]
      }
    }
  ]
}

FHIR Response Example

json

{
  "resourceType": "Bundle",
  "type": "collection",
  "total": 6,
  "entry": [
    {
      "resource": {
        "resourceType": "DiagnosticReport",
        "status": "final",
        "code": {
          "text": "AI-Powered Clinical Assessment"
        },
        "extension": [
          {
            "url": "https://pearmedica.com/fhir/Extension/triage-level",
            "valueCodeableConcept": {
              "coding": [{
                "system": "https://pearmedica.com/fhir/CodeSystem/triage-level",
                "code": "urgent",
                "display": "Urgent — Medical attention within hours"
              }]
            }
          },
          {
            "url": "https://pearmedica.com/fhir/Extension/assessment-confidence",
            "valueDecimal": 0.87
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Condition",
        "code": {
          "coding": [
            { "system": "https://pearmedica.com/fhir/CodeSystem/pearmedica", "code": "c_malaria", "display": "Plasmodium falciparum Malaria" },
            { "system": "http://hl7.org/fhir/sid/icd-10", "code": "B50.9", "display": "Plasmodium falciparum Malaria" }
          ],
          "text": "Malaria"
        },
        "severity": {
          "coding": [{ "system": "http://snomed.info/sct", "code": "6736007", "display": "Moderate" }]
        },
        "extension": [{
          "url": "https://pearmedica.com/fhir/Extension/condition-probability",
          "valueDecimal": 0.78
        }]
      }
    }
  ]
}

Terminology Systems

System	URI	Used For
SNOMED CT	http://snomed.info/sct	Symptoms, severity, clinical findings
ICD-10	http://hl7.org/fhir/sid/icd-10	Assessed conditions (diagnosis codes)
LOINC	http://loinc.org	Lab tests, vitals, observations
PearMedica Local	https://pearmedica.com/fhir/CodeSystem/pearmedica	Local symptom/condition IDs without standard binding

Switching to FHIR from the Proprietary API

Same auth — use the same API key and Bearer token header

Wrap your patient data in a FHIR Patient resource (gender + birthDate)

Wrap each symptom in a FHIR Observation resource (code + interpretation)

Bundle them into a FHIR Bundle (type: "collection")

POST to /api/v1/fhir/assess instead of /api/v1/assess

Parse the response as a FHIR Bundle containing DiagnosticReport + Condition resources