🚧

Results

When results are made available by the lab, the Lab Service automatically creates FHIR resources with the results including a DiagnosticReport (opens in a new tab) and associated Observations (opens in a new tab).

Result Types

There is some nuance to the types of results you can expect to receive. Below is the terminology these docs will use going forward:

Ordered Test Results: These are results that correspond to the order and specified orderable item code submitted via the Lab Service. These results can be preliminary or final.
Reflex Test Results: These are results for a test performed automatically by the lab based on the results found for the ordered test. For example, a more specific test may be warranted based on the result of the ordered test. These results will reference the Lab Service generated order number, but will indicate an orderable item code different from the orderable item code submitted in the original order. There is no method to predict whether or not a reflex test will be triggered. These results can arrive at any point after the ordered test has been submitted.
Unsolicited Test Results: These are results transmitted for an order that was not submitted through the Oyster Lab Service. This might happen if a patient walks into a lab patient service center and has a test performed and then transmitted to the patient's provider. These results will not have an order number that matches any order submitted through the Lab Service.

FHIR Modeling

Results are modeled as DiagnosticReport (opens in a new tab) and associated Observations (opens in a new tab). A DiagnosticReport is created for any result type.

Ordered Test and Reflex Test Results

The DiagnosticReports of ordered test results and reflex test results, both of which reference the Lab Service generated order number, are based on the ServiceRequest representing the ordered test.

In the example below, note that the DiagnosticReport.basedOn field references a ServiceRequest resource. All preliminary and final results for the ordered and reflex tests will reference the submitted ServiceRequest in this way.

Example DiagnosticReport

{
  "resourceType": "DiagnosticReport",
  "extension": [
    {
      "url": "https://extensions.fhir.oystehr.com/diagnostic-report-original-transmission",
      "extension": [
        {
          "url": "content",
          "valueAttachment": {
            "data": "TVNIfF5+XCZ8TEFCfEFMMXx8SW50ZWdyYXRpb24tdGVzdC13ZWJob29rLXJvdXRlLWxvY2FsLWRvcm4td2l0aC1kZXYtY3JlZHN8MjAyNTAzMDYxOTAxMDQtMDAwMHx8T1JVXlIwMV5PUlVfUjAxfDg2Y2E4NmMyLWYwYzMtNDM2MS04NmZlLWZlM2IxZjZlYzJiY3xUfDIuNS4xfHx8QUx8QUx8fHx8fExSSV9OR19STl9Qcm9maWxlXl4yLjE2Ljg0MC4xLjExMzg4My45LjIwXklTT3x8DVBJRHwxfHwyODJhMjdhZS1mODFlLTRkMmYtYTdjMS1mMDk2Y2NkYTk5OTVeXl5eUFR8fFNub3deSm9ufHwxOTk5MTIwMXxGfHx8fHx8fHx8fHx8fHx8fHx8fHx8fA1QVjF8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fA1PUkN8UkV8eWk4NzM2dzBuYmM0a2V5c290cTV8eWk4NzM2dzBuYmM0a2V5c290cTV8fHx8fHx8fHwxOTMyOTI5MTkxXkRvY3Rvcl5Hb29kXl5eXl5eXl5eXk5QSXx8fHx8fHx8fHx8fA1PQlJ8MXx5aTg3MzZ3MG5iYzRrZXlzb3RxNXx5aTg3MzZ3MG5iYzRrZXlzb3RxNXw1NzAyMS04XkNCQyBXIEF1dG8gRGlmZmVyZW50aWFsIHBhbmVsIGluIEJsb29kXkxOXl5eXl5eQ0JDIFcgQXV0byBEaWZmZXJlbnRpYWwgcGFuZWwgaW4gQmxvb2R8fHwyMDI1MDMwNjE5MDEwNC0wMDAwfHx8fHx8fHx8MTkzMjkyOTE5MV5Eb2N0b3JeR29vZF5eXl5eXl5eXl5OUEl8fHx8fHwyMDI1MDMwNjE5MDEwNC0wMDAwfHx8RnxOT1RfUFJPVklERUR8fHxOT1RfUFJPVklERUR8fHx8fHx8fHx8fHx8fHx8fHx8fHxOT1RfUFJPVklERUQNT0JYfDF8Tk18NzE4LTdeSGVtb2dsb2JpbiBbTWFzcy92b2x1bWVdIGluIEJsb29kXkxOXl5eXl5eSGVtb2dsb2JpbiBbTWFzcy92b2x1bWVdIGluIEJsb29kfDF8NS41fG1FcS9MfDIuNS01LjN8SHx8fEZ8fHwyMDI1MDMwNjE5MDEwNC0wMDAwfDFBXlN3aWZ0IExhYm9yYXRvcmllc143MzEgTWFya2V0IFN0XlNhbiBGcmFuY2lzY29eQ0FeOTQxMDN8fHx8fHx8fFN3aWZ0IExhYm9yYXRvcmllc15eXl5eXl5eXjFBfDczMSBNYXJrZXQgU3ReXlNhbiBGcmFuY2lzY29eQ0FeOTQxMDNeXl5eXl5eTk9UX1BST1ZJREVEXk5PVF9QUk9WSURFRHxOT1RfUFJPVklERUR8fHx8fHx8DQ==",
            "contentType": "base64",
            "creation": "2025-03-13T14:37:16.703-04:00"
          }
        },
        {
          "url": "standard",
          "valueCoding": {
            "code": "hl7",
            "version": "2.5.1"
          }
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/282a27ae-f81e-4d2f-a7c1-f096ccda9995"
  },
  "identifier": [
    {
      "value": "yi8736w0nbc4keysotq5",
      "use": "usual",
      "type": {
        "coding": [
          {
            "code": "FILL"
          }
        ],
        "text": "Filler entity id"
      }
    }
  ],
  "basedOn": [
    {
      "reference": "ServiceRequest/393ca506-9ef5-44f0-85c5-c8242593f370"
    }
  ],
  "result": [
    {
      "reference": "Observation/316192dd-5b9a-4923-903f-2a12d3e83eca"
    }
  ],
  "status": "final",
  "code": {
    "coding": [
      {
        "code": "57021-8",
        "system": "http://loinc.org",
        "display": "CBC W Auto Differential panel in Blood"
      }
    ]
  },
  "id": "6efb51c0-0cdc-41ab-8e19-af17074bc71f",
  "meta": {
    "versionId": "6ce82987-464c-4ffa-a2d1-0d4eaccd5b04",
    "lastUpdated": "2025-03-13T18:37:16.795Z"
  }
}

Preliminary and Final Results

Many labs choose to wait until a final result is ready before transmitting a result, but some labs may choose to share preliminary results in the interim. Microbiology orders are a good example, wherein a preliminary result may indicate current culture growth before the observation period has concluded.

A DiagnosticReport is created upon initial receipt of a result. The DiagnosticReport.status field is set to preliminary or final according to the status of the received result.

Any subsequent result updates for the same test and order are captured as versioned history on the initial DiagnosticReport.

For example, say a final result came in for the the order and test corresponding to the DiagnosticReport above. The DiagnosticReport would have the relevant fields updated--in particular, the status field would be set to final. To view any preliminary results, i.e. previous versions of the DiagnosticReport, you can query the DiagnosticReport's history using a call like the one below.

https://fhir-api.zapehr.com/r4/DiagnosticReport/6efb51c0-0cdc-41ab-8e19-af17074bc71f/_history

When a final result is received for the ordered test, the Lab Service, in addition to performing the updates outlined above, will also update the ServiceRequest on which the final result DiagnosticReport is based. The ServiceRequest.status will be updated to completed.

Unsolicited Results

By nature of being unsolicited, this result type will not match any order number or ServiceRequest generated by the Lab Service. A DiagnosticReport and associated Observations will be created when unsolicited results are received, but the DiagnosticReport will not be basedOn any ServiceRequest.

Patient information transmitted from the lab will be captured in on the DiagnosticReport. Your frontend application will need to implement a manual triage and matching process to ensure that unsolicited results are mapped to the correct Patient.

Testing the Results Flow

To test ordering and results in the sandbox, you can send orders to a mock lab called AutoLab. AutoLab accepts valid order requests and serves valid results. It is a very useful tool for testing the end to end flow of order submission and results receipt.

Note that there may be a delay of 5-10 minutes between when AutoLab receives a result and when a result is then available.

To test the end to end flow, start by creating a route to AutoLab and creating the necessary FHIR resources for submitting a lab. Then submit the order.

⚠️

While in sandbox mode, only orders submitted to AutoLab will be accepted.

When the result is ready, the Lab Service will automatically be alerted and fetch the result, creating a DiagnosticReport associated with the submitted ServiceRequest.

Submit an Order Messaging