Submit an Order

Now that your user has had an opportunity to explore the compendia and identify the correct test, it is time to submit an order to the lab!

The Lab Service (Submit Lab endpoint)[https://api-reference.oystehr.com/reference/post_submit (opens in a new tab)] requires that a valid ServiceRequest and Account Number be sent. The ServiceRequest (opens in a new tab) represents the order, while the account number comes from the Route you created for the lab. See Onboarding a Lab for instructions on managing Routes.

When the ServiceRequest is submitted, the Lab Service updates the ServiceRequest with a generated unique identifier. This value is sent to the lab as the order id.

Necessary FHIR Resources

At a high level, these are the resources necessary to submit an order as well as any field specific requirements.

Patient

• id, birthDate, and gender are required
• Must include name with use='official'
• Must include an address with use='home'

Encounter

• Encounter.class must include a code

Practitioner

• Must have a valid NPI with valid coding system, http://hl7.org/fhir/sid/us-npi
• Must have a name with use='official'

Location

Represents the office placing the order

Organization

Represents the lab

Coverage

Necessary if paying via insurance and optional otherwise. If no coverage is submitted, payment will default to self-pay.

• The Lab Service will also accept a self-pay Coverage resource with Coverage.type = 'pay'

• Coverage.subscriber is required and must map to the Patient or a RelatedPerson who is the primary insurance holder. The subscriber must have all of:

  • a name with use='official'
  • a valid address (including line, city, state, and postalCode) with use='home' -birthDate populated

• Include subscriberId

• If paying via insurance, Coverage.payor must include a reference of type Organization. This Organization must have a name and valid address (including line, city, state, and postalCode)

• Coverage.class must be a valid code from the coverage class (opens in a new tab) system

• Coverage.relationship must have a valid code

Account

Can be linked to the Patient or to a RelatedPerson. Captures responsible party/guarantor information.

• Organization guarantors must have a valid address
• Human guarantors must have a name and an address with use='home'

QuestionnaireResponse

Only required if the ordered test has an associated AOE

• Question answers must conform to question format. See AOE question validation

Specimen

Only required if performing in-house specimen collection

• Specimen.collection.collected must include a valid collection datetime

ServiceRequest

• Must have a priority
• A valid code field
• reasonCode must include at least one coding (i.e. diagnosis)

Anatomy of the ServiceRequest

The ServiceRequest FHIR resource represents an order requested by a provider submitted to a lab for a patient, who may or may not have insurance, during a particular encounter. As a result, there are various FHIR resources necessary that must be referenced by the ServiceRequest in order for the ServiceRequest to be valid. The ServiceRequest status field is updated by the Lab Service to track the order from creation to submission.

ServiceRequest Status

From the Lab Service perspective, a ServiceRequest will go through three stages, captured by its status.

Status: Draft

This is a ServiceRequest that has been created and is in the process of being populated with the necessary information. For example, a ServiceRequest may be created when a provider creates an order, but specimen collection has not been completed or answers to the AOE have not yet been populated. This ServiceRequest will remain in draft status until it is ready to be submitted to the lab.

Status: Active

This is a ServiceRequest that is ready for transmission to a lab. It has all necessary resources populated. The Lab Service Submit Lab endpoint (opens in a new tab) requires the ServiceRequest status be active.

Status: Completed

When a final result is received for the ordered test, the Lab Service automatically updates the status of the ServiceRequest to completed. Note that a completed ServiceRequest may still receive reflex results.

Example ServiceRequest

Let's take a look at the example below. This ServiceRequest has been fully populated and is in the active status, meaning it is ready to be submitted.

{
  "resourceType": "ServiceRequest",
  "status": "active",
  "intent": "order",
  "subject": {
    "reference": "Patient/1a9ee4e3-61cf-4943-a114-d9992ab39b5c"
  },
  "encounter": {
    "reference": "Encounter/b497fb89-9a43-4fb3-a146-e7ae05c2600b"
  },
  "insurance": [
    {
      "reference": "Coverage/de5f9023-7f34-4f3b-8381-d6ab75c2ca4b"
    }
  ],
  "requester": {
    "reference": "Practitioner/e2765fdb-a029-4ef6-a8b4-adb2c7ad82b6"
  },
  "priority": "routine",
  "reasonCode": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/valueset-icd-10",
          "code": "A00",
          "display": "Cholera"
        }
      ],
      "text": "Cholera"
    }
  ],
  "performer": [
    {
      "reference": "Organization/db61cceb-fb35-43d6-a7af-8cd865372736"
    }
  ],
  "locationReference": [
    {
      "reference": "Location/42fe32d8-9f56-468d-bb07-478b19f407a4"
    }
  ],
  "specimen": [
    {
      "reference": "Specimen/62d938d7-ad2a-4642-a335-d63feeb6af82"
    }
  ],
  "note": [
    {
      "text": "This is an optional field. Patient is a toddler"
    },
  ],
  "code": {
    "coding": [
      {
        "system": "https://terminology.fhir.oystehr.com/CodeSystem/oystehr-oi-codes",
        "code": "57021-8",
        "display": "CBC W Auto Differential panel in Blood"
      }
    ],
    "text": "Lab Test"
  },
  "supportingInfo": [
    {
      "reference": "QuestionnaireResponse/0d26ae3c-56e0-49c1-8de4-b494e86a69e3"
    }
  ],
  "id": "9adc1cc0-6452-43e2-a73d-dff153b977bb",
  "meta": {
    "versionId": "ae588dc9-d4ac-493a-9fe4-8846e8a49d60",
    "lastUpdated": "2025-03-05T22:41:05.712Z"
  },
  "identifier": [
    
  ]
}

Let's dissect this ServiceRequest:

This ServiceRequest is in the active status, and in fact has been submitted; all submitted ServiceRequests contain the Lab Service generated order number in their identifier field, identified by the lab-order-placer-id system.

Notice that the ServiceRequest relies on a Patient (opens in a new tab) reference describing the subject of the ordered test. An Encounter (opens in a new tab) describes the particular session during which the Practitioner (opens in a new tab) requested the order. The provider's office is captured by the Location (opens in a new tab) resource.

In this example, the patient has chosen to pay with insurance, represented by the Coverage (opens in a new tab) resource.

The lab filling the order is represented by an Organization (opens in a new tab). Below is an example Organization representing AutoLab lab. Note that the lab's labGuid, which can be found in the compendium, is included as an identifier.

{
  "resourceType": "Organization",
  "name": "AutoLab",
  "identifier": [
    {
      "system": "https://identifiers.fhir.oystehr.com/lab-guid",
      "value": "790b282d-77e9-4697-9f59-0cef8238033a"
    }
  ],
  "id": "fc02d3b4-6630-4085-858d-e8a8e281f6df",
  "meta": {
    "versionId": "6926b4cd-a66f-4101-bf65-c0f3098bfdcc",
    "lastUpdated": "2025-03-06T17:57:43.221Z"
  }
}

In this example, a Specimen (opens in a new tab) resource describing the collected specimen is included. In PSC workflows, in which the specimen will be collected at a lab's Patient Service Center, no Specimen will be sent with the ServiceRequest.

This ServiceRequest also includes Annotations (opens in a new tab) in the notes field. This is an optional field. Any notes included on the ServiceRequest at time of submission will be included in the transmission to the lab.

The reasonCode field contains a list of any pertinent diagnoses. These are ICD10 diagnosis codes. Every lab order must be submitted with at least one diagnosis code, although the specific order does not matter.

The code.coding field references the specific orderable item being ordered. For the moment, the Lab Service only supports a single test (orderable item) per order.

The QuestionnaireResponse representing the AOE responses are referenced in the supportingInfo.

The Order Number

During the submission process, the Lab Service automatically adds a generated order number to the ServiceRequest.identifier. This same order number is transmitted to the lab and will be referenced in the results the lab returns.

  "identifier": [
    {
      "system": "https://identifiers.fhir.oystehr.com/lab-order-placer-id",
      "value": "wihx4vj2ew5ybnnhe419"
    }
  ]