​

Concepts

Vital has a series of concepts to grasp regarding ordering:

• Lab Tests
• Lifecyle of an Order
• AoE
• Registrable Kits
• Scheduled Orders

In this document, we will focus on orderable panels/biomarkers.

​

Markers

Markers are individual, orderable tests, at the lab level. So, for example, at Labcorp you can order a Lipid Panel test and a Vitamin D test, a panel and a biomarker respectively. At Vital, these are both refered to as markers.

​

Lab Tests

Lab Tests are a collection of markers, or a preset combination of markers, that you can order. Using the example above, you can create a Labcorp Lipid Panel and Vitamin D lab test. You can then place orders at Vital using this preset. This is useful for situations where you repeatedly want to order the same markers.

​

Ordering

When placing an Order, you will see an order_set field. This is what defines what markers will be ordered.

There are multiple combinations allowed with this field, so let’s explore all of them.

​

Ordering a Lab Test

When ordering from one previously created Lab Test, the order_set field should be populated as follows:

​

Ordering from multiple Lab Tests

You may want to combine two or more existing Lab Tests without creating a new one. This is possible by doing:

​

Ordering without a Lab Test

This is what Vital calls à la carte ordering. You may want to order from the marker compendium without creating a preset.

It is possible to order a-la-carte using Vital marker_ids or the lab’s provider_id.

​

Order Lab Tests with extra Markers

You may also add extra markers to an order. For example, you want to order the Labcorp Lipid Panel and Vitamin D but for this particular patient, you also want to order a CBC Panel.

​

Collection Method

Further explored in the documentation, Vital also has the concept of Collection Method. Vital currently supports three methods, At Home Phlebotomy, Walk In Phlebotomy and Testkits. When ordering, you must select one of these, either at lab test creation, or at ordering time.

​

À La Carte Markers

As mentioned above, not all markers are a la carte orderable. You can find which one’s are orderable via the GET /v3/lab_tests/markers.

​

Error Cases

With the existance of various allowed combinations with the order_set field, there’s many validations that are done server side. Here are some of the errors you can expect to encounter:

​

400 Bad Request

1. collection_method must be set if add_on is set: When the add_on field is supplied, you must provide the collection_method.
2. marker_ids or provider_ids must be set in add_on: One of marker_ids or provider_ids must be set, if the add_on field is provided.
3. cannot set both marker_ids and provider_ids in add_on: Similarly, only one of the former fields can be provided.
4. cannot order lab_tests from multiple labs: You can only order multiple lab tests from the same lab.
5. cannot order with lab tests with multiple collection methods: You must supply a collection_method if ordering multiple lab tests with multiple collection methods.