Oystehr
Oystehr Services
Lab
Submit an Order
🚧

The Lab Service is currently in beta.

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 (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.

⚠️

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

Necessary FHIR Resources

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

⚠️

In order to submit a lab, both a Route and an Organization must exist. It is recommended to couple your Route creation workflow with the creation of the Organization representing the lab if one does not already exist.

Patient

  • id is required
  • birthDate is required
  • gender is required
  • Must include a name which will be selected based on this logic
  • Must include an address which will be selected based on this logic

Here is an example Patient with the necessary fields populated:

Example Patient
{
  "id": "2b34e60c-1141-401c-b1aa-726d755f59af",
  "resourceType": "Patient",
  "meta": {
    "versionId": "3f1d47b9-0f6a-4af9-8038-29224341a4b6",
    "lastUpdated": "2025-03-31T17:25:07.086Z"
  },
  "name": [
    {
      "use": "official",
      "given": [
        "Jane"
      ],
      "family": "Smith"
    }
  ],
  "gender": "female",
  "address": [
    {
      "use": "home",
      "city": "Washington",
      "line": [
        "12345 Example Street"
      ],
      "state": "DC",
      "postalCode": "54321"
    }
  ],
  "telecom": [
    {
      "value": "(098) 765-4321",
      "system": "phone"
    }
  ],
  "birthDate": "1980-02-01",
  "extension": [
    {
      "url": "https://fhir.zapehr.com/r4/StructureDefinitions/race",
      "valueCodeableConcept": {
        "coding": [
          {
            "code": "2028-9",
            "system": "http://terminology.hl7.org/CodeSystem/v3-Race",
            "display": "Asian"
          }
        ]
      }
    },
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
      "valueString": "Not Hispanic or Latino"
    }
  ]
}

Encounter

  • Encounter.class must include a valid code from the http://terminology.hl7.org/CodeSystem/v3-ActCode system.
Example Encounter
{
  "id": "ea35c5d5-561b-43ed-8561-ccb06b51e10e",
  "resourceType": "Encounter",
  "status": "planned",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB"
  },
  "subject": {
    "reference": "Patient/2b34e60c-1141-401c-b1aa-726d755f59af"
  },
  "meta": {
    "versionId": "b180c402-dc96-48ba-b47f-b8a43fc7aef7",
    "lastUpdated": "2025-03-31T17:25:07.565Z"
  }
}

Practitioner

  • Must have a valid NPI with valid coding system, http://hl7.org/fhir/sid/us-npi
  • Must include a name which will be selected based on this logic

Here is an example Practitioner resource with the correct NPI and name formats:

Example Practitioner
{
  "id": "5f887104-99b0-4492-9a82-fa35bccf7e99",
  "resourceType": "Practitioner",
  "meta": {
    "versionId": "6e77c971-0391-4c41-9114-1edfe2317b8a",
    "lastUpdated": "2025-03-28T04:48:20.323Z"
  },
  "name": [
    {
      "use": "official",
      "given": [
        "Good"
      ],
      "family": "Doctor"
    }
  ],
  "identifier": [
    {
      "value": "1932929191",
      "system": "http://hl7.org/fhir/sid/us-npi"
    }
  ]
}

Location

Represents the office placing the order.

  • The address must be populated
Example Location
{
  "id": "b204fd19-f87f-4416-b00e-fc176fb7b3e2",
  "resourceType": "Location",
  "name": "Example Place",
  "address": {
    "line": [
      "12345 Location St"
    ],
    "city": "Alexandria",
    "state": "VA",
    "postalCode": "22222"
  },
  "meta": {
    "versionId": "f747eedc-812e-4e74-a5b3-33153b20258f",
    "lastUpdated": "2025-03-31T17:25:08.147Z"
  }
}

Organization

Represents the lab. Here we have an example representing AutoLab. Note that the lab's labGuid, which can be found in the compendium, is included as an identifier; this value is required.

Example Organization
{
  "id": "09518019-5e16-4982-9840-f01410d1673c",
  "resourceType": "Organization",
  "name": "AutoLab",
  "identifier": [
    {
      "system": "https://identifiers.fhir.oystehr.com/lab-guid",
      "value": "790b282d-77e9-4697-9f59-0cef8238033a"
    }
  ],
  "meta": {
    "versionId": "be7e78b2-4447-48e8-a323-340f32824936",
    "lastUpdated": "2025-03-31T17:25:07.786Z"
  }
}

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 (opens in a new tab) who is the primary insurance holder. The subscriber must have all of:

    • Must include a name which will be selected based on this logic
    • Must include an address (including line, city, state, and postalCode) which will be selected based on this logic
    • 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

Example Coverage for Insurance
  {
    "resourceType": "Coverage",
    "status": "active",
    "beneficiary": {
      "reference": "Patient/2081005d-94be-4f19-9a8b-ec2df47cbe34"
    },
    "subscriber": {
      "reference": "RelatedPerson/1e7440f1-03b0-40be-8088-ec52bd361da9"
    },
    "payor": [
      {
        "reference": "Organization/eb075bc1-5c09-45af-bbe0-271cd449d2d1"
      }
    ],
    "class": [
      {
        "type": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/ValueSet/coverage-class",
              "code": "class"
            }
          ]
        },
        "value": "HMO"
      },
      {
        "type": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/ValueSet/coverage-class",
              "code": "group"
            }
          ]
        },
        "value": "GRP40600",
        "name": "Employer Name"
      }
    ],
    "relationship": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
          "code": "parent"
        }
      ]
    },
    "subscriberId": "1234567890",
    "id": "9df896c4-e2ee-4485-80b8-8ada680074ed",
    "meta": {
      "versionId": "d508a79a-02b5-4add-80f2-1e14f91709de",
      "lastUpdated": "2025-04-01T20:55:32.294Z"
    }
  }

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'
Example Account
{
  "resourceType": "Account",
  "status": "active",
  "subject": [
    {
      "reference": "Patient/2b34e60c-1141-401c-b1aa-726d755f59af"
    }
  ],
  "guarantor": [
    {
      "party": {
        "reference": "RelatedPerson/f38ef871-1d75-45ad-83cb-985c26c7179e"
      }
    }
  ],
  "id": "7bbade9b-746f-423c-bf61-8fa59f4f67bb",
  "meta": {
    "versionId": "9eb18333-a4b5-4ee0-9e90-8f5b4ed641d4",
    "lastUpdated": "2025-03-31T17:25:08.019Z"
  }
}

QuestionnaireResponse

Only required if the ordered test has an associated AOE. Note that the question linkIds correspond to the questions in the original AOE Questionnaire, queryable via the url in the questionnaire field.

Example QuestionnaireResponse
{
  "id": "5cab296a-d510-4d6a-918e-57f882cb6af1",
  "resourceType": "QuestionnaireResponse",
  "status": "completed",
  "questionnaire": "https://labs-api.zapehr.com/v1/canonical-questionnaire/lab/790b282d-77e9-4697-9f59-0cef8238033a/compendium/VZieAHtqKwWQuqb_C3TI6OzWQWUGN54R/item/57021-8/questionnaire",
  "item": [
    {
      "linkId": "fnGTTFtCXBLCunRi1MMF2Q",
      "answer": [
        {
          "valueString": "Jon Snow"
        }
      ]
    },
    {
      "linkId": "6szLG2rE8mLaOCCAUyZspw",
      "answer": [
        {
          "valueBoolean": true
        }
      ]
    },
    {
      "linkId": "0fSAyjtkhjgo6RL54gIG6w",
      "answer": [
        {
          "valueString": "blue"
        }
      ]
    },
    {
      "linkId": "Z5WuWa3O60MJF2WzF3rgYw",
      "answer": [
        {
          "valueString": "Kar-Tukulti-Ninurta"
        },
        {
          "valueString": "Nineveh"
        }
      ]
    },
    {
      "linkId": "URO2yMFH7MUQaLCD5_NzyQ",
      "answer": [
        {
          "valueDecimal": 12.34
        }
      ]
    }
  ],
  "meta": {
    "versionId": "e7d30b16-8425-4a96-a441-3dbb7f580a64",
    "lastUpdated": "2025-03-31T17:25:45.746Z"
  }
}

Specimen

Only required if performing in-house specimen collection

  • Either Specimen.collection.collectedDateTime or Specimen.collection.collectedPeriod.start must include a valid collection datetime
Example Specimen
{
  "resourceType": "Specimen",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0487",
        "code": "BLDA",
        "display": "Blood"
      }
    ]
  },
  "container": [
    {
      "specimenQuantity": {
        "value": 1
      }
    }
  ],
  "collection": {
    "collectedPeriod": {
      "start": "2025-03-24T10:45:05.971-04:00",
      "end": "2025-03-24T12:45:06.001-04:00"
    },
    "fastingStatusCodeableConcept": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v2-0916",
          "code": "F"
        }
      ]
    }
  },
  "id": "2f410150-da55-4263-87ff-c264169b7002",
  "meta": {
    "versionId": "d0a62062-d9a6-4681-b842-c80990371c96",
    "lastUpdated": "2025-03-24T14:45:10.960Z"
  }
}

ServiceRequest

  • Must have a priority
  • A valid code field. The system can reference either the orderable items (https://terminology.fhir.oystehr.com/CodeSystem/oystehr-oi-codes) or LOINC codes (opens in a new tab).
  • reasonCode must include at least one coding (i.e. diagnosis)

Name Specification on Resources

For resources associated with the order and that contain a name field, the Lab Service will select a name from the name array based on the following hierarchy:

  1. If the resource is submitted with the following extension, the Lab Service will use the name found at name[idx]. The extension must indicate https://fhir.zapehr.com/r4/StructureDefinitions/labs-name-idx as the url, and the desired index (idx) to use must be captured in the valueInteger. Below is an example of this extension, indicating that name[1] should be used. Please note that the array is zero-indexed:
{
  url: 'https://fhir.zapehr.com/r4/StructureDefinitions/labs-name-idx',
  valueInteger: 1,
},
  1. If a name with use='official' is included, the lab order will be submitted using this name.
  2. Finally, if neither of the above are included, the lab order will be submitted using the first name in the array.

Address Specification on Resources

For resources associated with the order and that contain a address field, the Lab Service will select an address from the address array based on the following hierarchy:

  1. If the resource is submitted with the following extension, the Lab Service will use the address found at address[idx]. The extension must indicate https://fhir.zapehr.com/r4/StructureDefinitions/labs-address-idx as the url, and the desired index (idx) to use must be captured in the valueInteger. Below is an example of this extension, indicating that address[0] should be used. Please note that the array is zero-indexed:
{
  url: 'https://fhir.zapehr.com/r4/StructureDefinitions/labs-address-idx',
  valueInteger: 0,
},
  1. If an address with use='home' is included, the lab order will be submitted using this address.
  2. Finally, if neither of the above are included, the lab order will be submitted using the first address in the array.

See Example ServiceRequest for a full example with expalanations.

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.

Example Submitted ServiceRequest
{
  "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). You can find an example Organization above.

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.

ServiceRequest Order number
  "identifier": [
    {
      "system": "https://identifiers.fhir.oystehr.com/lab-order-placer-id",
      "value": "wihx4vj2ew5ybnnhe419"
    }
  ]
Onboarding a LabResults