Oystehr
Oystehr Services
Lab
Explore the Compendium
🚧

The Lab Service is currently in beta.

Explore the Compendium

A compendium is the list of all orderable items that a lab offers. Compendia can have as few as one or potentially hundreds of orderable items. A lab may update its compendium from time to time to include new tests, remove old tests, or make changes to preexisting tests. A compendium is defined by its lab and its version.

An orderable item is an individual test offered by a lab, for example a strep test or a Complete Blood Count (CBC) test. Orderable items describe the test being ordered including the identifying code, any sample information including collection instructions, Answer on Entry (AOE) questions, and more.

⚠️

If your project is running in sandbox mode, you will only receive sandbox data from Orderable Item Search and the Get Canonical AOE Questionnaire endpoints. The reverse is true for projects running in production mode.

Compendium Updates

When labs update their compendia, the Oystehr Lab Service automatically picks up the changes and publishes a new version so that you will always be querying the latest version.

Orderable Item Search

The Lab Service makes this endpoint available to enable exploration of the compendia of all labs currently available through our lab integrator partner, DORN.

The orderable item search endpoint will return active orderable items for a lab's latest compendium version. You can control which results are returned using the various query parameters supported by the endpoint. By default the endpoint will return 25 results and then paginate. The maximum number of results is 100. Read more about making a request to the orderable item search endpoint here (opens in a new tab).

Example Orderable Item

Here is an example of an orderable item:

{
  "lab": {
    "labGuid": "790b282d-77e9-4697-9f59-0cef8238033a",
    "labName": "AutoLab",
    "labType": "Laboratory",
    "compendiumVersion": "VZieAHtqKwWQuqb_C3TI6OzWQWUGN54R"
  },
  "item": {
    "itemCode": "30341-2",
    "itemLoinc": "30341-2",
    "itemType": "Lab Test",
    "itemName": "Erythrocyte sedimentation rate",
    "uniqueName": "30341-2_Erythrocyte sedimentation rate",
    "specimens": [],
    "components": [],
    "cptCodes": [],
    "aoe": null
  }
}

Lab information is included with every orderable item as well as the compendium version currently served. A given orderable item is uniquely identified by its labGuid, itemCode, and compendiumVersion. From an ordering perspective, the itemCode and labGuid are sufficient identifiers for the lab to perform the desired test.

Additional fields not shown in the example above include specimens, components, CPT codes, and AOEs. Let's briefly look at each.

Specimens

Specimens describe the physical samples that must be collected in order for the lab to perform the ordered test. An orderable item can specify zero or many specimens.

Here is an example specimen:

Example Orderable Item Specimen
{
  "container": "Urine collection cup and transfer tube with preservative. Recommend transfer tubes with preservative including BD C&S Vacutainer(R) tubes, or BD UAP Vacutainer(R) tubes (Becton, Dickenson), or Aspirin Works TM tubes containing Chlorstat tablets. Order thr",
  "volume": "9 mL",
  "minimumVolume": "Not Available",
  "storageRequirements": "Freeze on arrival (at LabCorp) Stability: Refrigerated for 24 hours",
  "collectionInstructions": "Label a urine collection cup with the patient's name, and provide the patient with instructions for collecting a random urine sample. Transfer urine within 24 hours of collection into the appropriate transport tube containing preservative. Fill tube with urine sample, ie, approximately 9 mL and no less than 6 mL minimum volume. Seal tightly with screw cap and invert the tube several times. Discard remainder of urine sample. Freeze transport tube."
}

Components

Components describe the sub-parts that comprise a test. Component information helps providers understand exactly what is tested in a particular orderable item. Orderable items can specify zero or many components.

Here is an example component:

Example Orderable Item Component
{
  "componentItemCode": "013672",
  "name": "Creatinine, Urine",
  "loinc": "2161-8",
  "uom": "mg/dL",
  "range": "16.0-327.0",
  "type": "Numeric"
}

CPT Codes

CPT codes are used when billing for services and medical procedures; the service unit counts describe how many units of the CPT code are billed.

Example Orderable Item CPT Code
{
  "cptCode": "82570",
  "serviceUnitsCount": 3
}

AOE

AOE stands for "Answer on Entry" and describes a set of questions that accompany some but not all orderable items. AOEs and the questions asked are specific to the test itself. If an orderable item has an AOE associated with it, the required AOE questions must be answered and sent when submitting a lab order. AOEs are modeled as FHIR Questionnaires (opens in a new tab), and their responses are modeled as FHIR QuestionnaireResponses (opens in a new tab). Below is an example AOE Questionnaire.

Example Orderable Item AOE Questionnaire
{
  "resourceType": "Questionnaire",
  "status": "active",
  "url": "https://labs-api.zapehr.com/v1/canonical-questionnaire/lab/790b282d-77e9-4697-9f59-0cef8238033a/compendium/VZieAHtqKwWQuqb_C3TI6OzWQWUGN54R/item/57021-8/questionnaire",
  "item": [
    {
      "linkId": "fnGTTFtCXBLCunRi1MMF2Q",
      "text": "What is your name?",
      "type": "text",
      "required": true,
      "code": [
        {
          "system": "790b282d-77e9-4697-9f59-0cef8238033a-original-question-code",
          "code": "NAME"
        }
      ]
    },
    {
      "linkId": "6szLG2rE8mLaOCCAUyZspw",
      "text": "Do you seek the Holy Grail?",
      "type": "boolean",
      "required": true,
      "code": [
        {
          "system": "790b282d-77e9-4697-9f59-0cef8238033a-original-question-code",
          "code": "QUEST"
        }
      ]
    },
    {
      "linkId": "0fSAyjtkhjgo6RL54gIG6w",
      "text": "What is your favorite color?",
      "type": "choice",
      "required": true,
      "code": [
        {
          "system": "790b282d-77e9-4697-9f59-0cef8238033a-original-question-code",
          "code": "COLOR"
        }
      ],
      "answerOption": [
        {
          "id": "blue",
          "valueString": "blue"
        },
        {
          "id": "yellow",
          "valueString": "yellow"
        }
      ]
    },
    {
      "linkId": "Z5WuWa3O60MJF2WzF3rgYw",
      "text": "What is the capital of Assyria?",
      "type": "choice",
      "required": false,
      "code": [
        {
          "system": "790b282d-77e9-4697-9f59-0cef8238033a-original-question-code",
          "code": "CAPITAL"
        }
      ],
      "answerOption": [
        {
          "id": "Assur",
          "valueString": "Assur"
        },
        {
          "id": "Dur-Sharrukin",
          "valueString": "Dur-Sharrukin"
        },
        {
          "id": "Harran",
          "valueString": "Harran"
        },
        {
          "id": "Kar-Tukulti-Ninurta",
          "valueString": "Kar-Tukulti-Ninurta"
        },
        {
          "id": "Nimrud",
          "valueString": "Nimrud"
        },
        {
          "id": "Nineveh",
          "valueString": "Nineveh"
        }
      ],
      "extension": [
        {
          "url": "https://fhir.zapehr.com/r4/StructureDefinitions/data-type",
          "valueString": "multi-select list"
        }
      ]
    },
    {
        "linkId": "URO2yMFH7MUQaLCD5_NzyQ",
        "text": "What is the air-speed velocity of an unladen sparrow?",
        "type": "decimal",
        "required": false,
        "code": [
            {
                "system": "790b282d-77e9-4697-9f59-0cef8238033a-original-question-code",
                "code": "VELOCITY"
            }
        ],
        "extension": [
            {
                "url": "https://fhir.zapehr.com/r4/StructureDefinitions/formatted-input-requirement",
                "valueString": "###.##"
            }
        ]
    }
  ]
}
AOE Question Types

AOE question types include:

  • text
  • boolean
  • choice (for single- and multi-select)
  • decimal
  • integer
  • date

Certain question types, such as choice, decimal, integer, and date questions, rely on an extension which can describe how many answers the question can accept (multi-select), or the format of a date or number answer.

AOE Question Validation

Answers to questions with extensions referencing the formatted-input-requirement url must meet the format described in the valueString to be valid.

Example Formatted Input
{
  "url": "https://fhir.zapehr.com/r4/StructureDefinitions/formatted-input-requirement",
  "valueString": "###.##"
}

The valueString describing Date question formats will describe the expected year, day and month combinations. For example, the format YYYYMMDD would match 20250218 but not 2024218. Any combination of years, months, and days are possible.

Decimal and integer type questions will include extensions with valueStrings that describe the number of digits before and after the decimal point (if present). Here are some example formats and conforming values:

# -- a single digit. 1 or 9 are valid. 19 is invalid

## -- at most two digits. 23 and 8 are valid. 123 is invalid.

### -- at most three digits. 2, 82, and 123 are valid. 1002 is invalid. The pattern can be repeated as many times as necessary.

##.# -- at most two digits before the decimal, and exactly one after the decimal. 42.3 and 1.5 are valid. 123.9 and 12.44 are invalid.

Occasionally, text type questions will also include a particular format in the extension. Here are some examples:

a -- an alphanumeric string of length 1. 'P' or '2' are valid. 'RR' is invalid

aa -- an alphanumeric string with at most length 2. 'P' and 'r1' are valid. 'GRN' is invalid

aaa -- an alphanumeric string with at most length 3. 'GRN' is valid. 'Green' is invalid. The pattern can be repeated as many times as necessary.

s -- an alphanumeric string including special characters of length 1. 'P' or '?' are valid. 'RR' is invalid

ss -- an alphanumeric string with at most length 2. 'P' and '2#' are valid. 'GRN' is invalid

sss -- an alphanumeric string with at most length 3. 'GR!' is valid. 'Green' is invalid. The pattern can be repeated as many times as necessary.
AOE Response

The response to an AOE is modeled as a QuestionnaireResponse (opens in a new tab). Below is an example response to the AOE Questionnaire above. Note that questions are related by linkId:

Example AOE QuestionnaireResponse
{
  "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": "First Last"
        }
      ]
    },
    {
      "linkId": "6szLG2rE8mLaOCCAUyZspw",
      "answer": [
        {
          "valueBoolean": true
        }
      ]
    },
    {
      "linkId": "0fSAyjtkhjgo6RL54gIG6w",
      "answer": [
        {
          "valueString": "blue"
        }
      ]
    },
    {
      "linkId": "Z5WuWa3O60MJF2WzF3rgYw",
      "answer": [
        {
          "valueString": "Kar-Tukulti-Ninurta"
        },
        {
          "valueString": "Nineveh"
        }
      ]
    },
    {
      "linkId": "URO2yMFH7MUQaLCD5_NzyQ",
      "answer": [
        {
          "valueDecimal": 52.08
        }
      ]
    }
  ],
  "id": "b3ba8566-13ad-425f-b627-bcc7de228ae5",
  "meta": {
    "versionId": "97bea423-0175-4734-9e1b-8e65d47a3d95",
    "lastUpdated": "2025-03-04T19:25:44.814Z"
  }
}

The AOE question types are mapped to the appropriate FHIR value type as follows:

Questionnaire Question TypeQuestionnaire Response Value Type
textvalueString
booleanvalueBoolean
choiceanswer array of corresponding type
decimalvalueDecimal
integervalueInteger
datevalueDate

Get Canonical AOE Questionnaire

The Lab Service provides an endpoint to retrieve the AOE Questionnaire for a given item (if it exists). You may find this functionality useful when building your interface to populate the AOE.

For example, the AOE depicted above could be queried by making the appropriate request to

https://labs-api.zapehr.com/v1/canonical-questionnaire/lab/790b282d-77e9-4697-9f59-0cef8238033a/compendium/VZieAHtqKwWQuqb_C3TI6OzWQWUGN54R/item/57021-8/questionnaire

Notice that this request requires the labGuid, the compendium version, and the code for the item in question.

You can read more about the specifics of this endpoint here (opens in a new tab).

LabOnboarding a Lab