## How results arrive in Medplum

This guide explains how laboratory results are handled in the Medplum-Health Gorilla labs integration.

When Health Gorilla receives results from performing laboratories (Quest, Labcorp, regional labs, etc.), they are synchronized into your Medplum project as structured FHIR resources. The sections below describe the resulting data model and how results are matched to orders and patients.

## Key Concepts

Understanding how results are structured and connected is essential for building clinical workflows and displaying results to providers.

| Concept | Description |
| --- | --- |
| Unsolicited Results | Lab values delivered as machine-readable FHIR `Observations` |
| Performing Lab Details | `Organization` information for the specific lab that processed specimens |
| Health Gorilla PDF Report | `DocumentReference` containing CLIA-certified lab report in a format that is consistent across all performing labs |
| Clinical Lab PDF Report | `DocumentReference` containing the original lab report delivered by the performing lab |
| Structured Lab Results | Lab values delivered as machine-readable FHIR `Observations` |

## FHIR Data Model

Laboratory results are represented as a suite of resources that preserve both structured and unstructured data for clinical workflows and original documentation for regulatory compliance.

In this section, we describe the primary resources used in Health Gorilla lab results.

### Result Resource Types

#### DiagnosticReport

The `DiagnosticReport` serves as the primary container for all results related to a specific order, providing summary information and organizing individual observations.

**Key Fields:**

| Field | Description |
| --- | --- |
| `DiagnosticReport.basedOn` | References the original [order `ServiceRequest`](/content/docs/integration/health-gorilla/sending-orders#order-structure/index.html) that generated this result |
| `DiagnosticReport.identifier` | Contains multiple identifiers: <br>- Health Gorilla's unique identifier for the report<br>- **Placer ID**: The order identifier assigned by the _ordering system_ (e.g., your EMR).<br>- **Filler ID**: The order identifier assigned by the _performing lab_.<br>- **Lab's accession number**: A unique identifier assigned by the performing laboratory to the specific _specimen_ when it is received. |
| `DiagnosticReport.result` | Array of references to individual `Observation` resources containing lab values |
| `DiagnosticReport.presentedForm` | References to PDF reports from Health Gorilla |
| `DiagnosticReport.status` | Result status (`preliminary`, `final`, `amended`, `corrected`) |
| `DiagnosticReport.effectiveDateTime` | When specimens were collected |
| `DiagnosticReport.issued` | When results were released by the lab |

**Example Structure:**

```js
{

"resourceType": "DiagnosticReport",

"identifier": [
    {
      "system": "https://www.healthgorilla.com",
      "value": "7890"
    },
    {
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "ACSN",
          "display": "Accession ID"
        }],
        "text": "Accession Number"
      },
      "value": "CF020052R"
    },
    {
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "PLAC",
          "display": "Placer"
        }],
        "text": "Placer"
      },
      "value": "1452503"
    }
  ],
  "status": "final",
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "58410-2",
      "display": "Complete blood count (CBC) panel"
    }]
  },
  "basedOn": [{
    "reference": "ServiceRequest/original-order-123"
  }],
  "subject": {
    "reference": "Patient/4556",
    "display": "Homer Simpson"
  },
  "performer": [{
    "reference": "Organization/abcdef",
    "display": "Quest"
  }],
  "effectiveDateTime": "2025-06-27T00:41:00Z",
  "issued": "2025-06-30T15:34:54Z",
  "result": [{
    "reference": "Observation/wbc-count-456"
  },
  {
    "reference": "Observation/rbc-count-789"
  },
  {
    "reference": "Observation/clinical-lab-report-999"
  }],
  "presentedForm": [{
    "contentType": "application/pdf",
    "url": "https://storage.medplum.com/binary/123",
    "title": "DiagnosticReport-7890.pdf"
  }]
}
```

### Observations

Individual lab values are represented as `Observation` resources, with each test result getting its own observation. Health Gorilla provides rich metadata including reference ranges, abnormal flags, and performing lab details.

**Standard Lab Value Observations:**

| Field | Description |
| --- | --- |
| `Observation.code` | LOINC code for the specific test |
| `Observation.value[x]` | The measured value (Quantity, CodeableConcept, or string) |
| `Observation.referenceRange` | Normal ranges provided by the performing lab |
| `Observation.interpretation` | Abnormal flags (High, Low, Critical, etc.) |
| `Observation.note` | Additional clinical notes or comments about the test result |
| `Observation.performer` | `Organization` reference to the specific lab location that performed the test |

```js
{
  "resourceType": "Observation",
  "status": "final",
  "identifier": [
    {
      "system": "https://www.healthgorilla.com",
      "value": "7890-6690-2"
    }
  ],
  "subject": {
    "reference": "Patient/4556",
    "display": "Homer Simpson"
  },
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "6690-2",
      "display": "Leukocytes [#/volume] in Blood by Automated count"
    }]
  },
  "valueQuantity": {
    "value": 7.2,
    "unit": "10*3/uL",
    "system": "http://unitsofmeasure.org"
  },
  "interpretation": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v2-0078",
      "code": "H",
      "display": "Above high normal"
    },
    {
      "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
      "code": "H",
      "display": "Above high normal"
    },
    {
      "system": "https://www.healthgorilla.com/observation-interpretation",
      "code": "H",
      "display": "Above high normal"
    }],
    "text": "Above high normal"
  }],
  "note": [{
    "text": "Fasting reference interval. "
  }],
  "referenceRange": [{
    "low": { "value": 4.5 },
    "high": { "value": 11.0 }
  }],
  "performer": [{
    "reference": "Organization/quest-lab-location-123"
  }]
}
```

### DocumentReference

Unstructured PDF reports are stored as `DocumentReference` resources, with different types serving different purposes in the clinical workflow.

**Health Gorilla Standard PDF:**

- Referenced by `DiagnosticReport.presentedForm`
- Standardized format across all labs
- Optimized for electronic health record display

**Lab-Branded PDFs:**

- Referenced by the "clinical lab report" observation via `derivedFrom`
- Original lab formatting (Quest, Labcorp, regional lab branding)
- Preferred for patient communication and external sharing

```json
{
  "resourceType": "DocumentReference",
  "status": "current",
  "docStatus": "final",
  "category": [{
    "coding": [{
      "system": "https://www.medplum.com/integrations/health-gorilla/document-type",
      "code": "DiagnosticReport"
    }]
  }],
  "subject": {
    "reference": "Patient/4556",
    "display": "Homer Simpson"
  },
  "identifier": [{
    "system": "https://www.healthgorilla.com",
    "value": "123456"
  }],
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://storage.medplum.com/binary/87654",
      "title": "DiagnosticReport-123456.pdf"
    }
  }]
}
```

### Detected Issues

The Medplum Health Gorilla integration creates `DetectedIssue` resources to flag clinical workflow concerns.

**Common Issue Types:**

| Issue Type | Description |
| --- | --- |
| **Unsolicited Report** | Results received for a patient without a corresponding order in your system |
| **Unknown Patient** | Results received for a patient not found in your patient database |

```js
{
  "resourceType": "DetectedIssue",
  "code": {
    "coding": [{
      "system": "https://www.medplum.com/integrations/health-gorilla/issue-type",
      "code": "unsolicited-diagnostic-report"
    }]
  },
  "implicated": [{
    "reference": "DiagnosticReport/123abc"
  }]
}
```

### Organizations

Health Gorilla returns detailed information about the performing laboratory for each observation. If the corresponding lab does not exist inside your Medplum project, `receive-from-health-gorilla` will create the corresponding `Organization` resource and link it to each observation.

**Key Information Captured:**

- Lab name and location details
- Physical address
- Lab director contact information

```js
{
  "resourceType": "Organization",
  "name": "Quest Diagnostics - Regional Lab 123",
  "address": [{
    "line": ["1234 Lab Drive"],
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102"
  }],
  "partOf": {
    "reference": "Organization/quest-lab-location-123",
    "display": "Quest"
  },
  "contact": [{
    "purpose": {
      "coding": [{
        "system": "http://hl7.org/fhir/contactentity-type",
        "code": "ADMIN"
      }]
    },
    "name": {
      "text": "Ronald McDonald CLS"
    }
  }],
}
```

## Resolving Orders with Results

When a result is received, Medplum attempts to match it to an existing order (`ServiceRequest`).

**Processing Logic:**

1. `receive-from-health-gorilla` first attempts to match the incoming result to an existing order by checking:
   - `basedOn` references (which contain the requisition ID)
   - **Accession number (`ACSN` identifier)**: A unique identifier assigned by the _performing laboratory_ (e.g., Quest, Labcorp) to the specific specimen(s) when they are received and logged into their system.
   - **Placer number (`PLAC` identifier)**: The order ID assigned by the _ordering system_ (e.g., your EMR, Medplum, or the clinic) that placed the order.
   - **Filler number (`FILL` identifier)**: The order ID assigned by the _fulfilling system_ (the performing laboratory) that carries out the order.
2. If a matching order is found, the result is linked to that order. The patient associated with that order is used, preventing duplicate patients or `unknown-patient` issues.
3. If no matching order is found, the result is considered "unsolicited". The bot then attempts to match the result to a patient using the patient's Health Gorilla identifier.
4. If a matching patient exists, the result is imported normally, but without a `DiagnosticReport.basedOn` reference, and a `DetectedIssue` with code `unsolicited-diagnostic-report` is created.
5. If no patient match is found, a new `Patient` resource is created using the demographic information provided by the lab, and a `DetectedIssue` with code `unknown-patient` is created.

## Backfilling missed results

If results are missing in Medplum but visible in the Health Gorilla portal, check that subscriptions are active (`setup-subscriptions`) and that the callback bot URL is current. When webhooks were down or never configured for a period, use [`sync-resources-from-health-gorilla`](/content/docs/integration/health-gorilla/sync-resources-from-health-gorilla/index.html) to backfill:

1. Choose a `startDate` and `endDate` that bracket the gap (based on `_lastUpdated` in Health Gorilla).
2. Run a `DiagnosticReport` sync with `syncOnlyMissing: true` to avoid re-processing resources already in Medplum.
3. Review `DetectedIssue` resources for any remaining [unsolicited or unknown-patient](/content/docs/integration/health-gorilla/receiving-results#resolving-orders-with-results/index.html) cases, especially in receive-only migrations without placeholder orders.

For receive-only migrations, syncing placeholder `ServiceRequest` orders with matching Placer or Accession identifiers before backfilling results reduces unsolicited reports.

## Lab-specific Behavior

### Quest

- **Preliminary Results**: Quest sends preliminary results on a rolling basis, and will send the same report multiple times, updating Medplum's `DiagnosticReport` resource _in-place_. Monitor the value of `DiagnosticReport.status` to see when the report has been finalized. The same in-place updates apply when the report is imported via manual sync.