​
Concepts

Vital has a series of concepts to grasp regarding ordering: 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: 
from vital.client import Vital
from vital.environment import VitalEnvironment

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

client.lab_tests.create_order(
        order_set=OrderSet(
            lab_test_ids=["lab_test_id"]
        )
        ...
)

​
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: 
from vital.client import Vital
from vital.environment import VitalEnvironment

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

client.lab_tests.create_order(
        order_set=OrderSet(
            lab_test_ids=["lab_test_id1", "lab_test_id_2"]
        )
        ...
)

​
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.
This is a team level configuration that must be requested from Vital. Not all markers can be ordered in this manner.
It is possible to order a-la-carte using Vital marker_ids or the lab’s provider_id. 
from vital.client import Vital
from vital.environment import VitalEnvironment

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

client.lab_tests.create_order(
        order_set=OrderSet(
            add_on=AddOn(
                provider_ids=["322022"]
                # marker_ids=[1] 
            )
        ),
        collection_method="walk_in_test",
        ...
)

​
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. 
from vital.client import Vital
from vital.environment import VitalEnvironment

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

client.lab_tests.create_order(
        order_set=OrderSet(
            lab_test_ids=["lab_test_id"],
            add_on=AddOn(
                provider_ids=["322022"]
                # marker_ids=[1] 
            )
        ),
        collection_method="walk_in_test",
        ...
)
When supplying the add_on field, it is always required to provide the collection_method field.

​
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. 
from vital.client import Vital
from vital.environment import VitalEnvironment

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

client.lab_tests.create_order(
        order_set=OrderSet(
            lab_test_ids=["lab_test_id"],
        ),
        collection_method="walk_in_test",
        ...
)

​
À 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. 
from vital.client import Vital
from vital.environment import VitalEnvironment

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

markers = client.lab_tests.get_markers(
        name="322022",
        a_la_carte_enabled=True
)

if not all([m.a_la_carte_enabled for m in markers.markers]):
    raise Exception("Markers not a_la_carte_enabled")

​
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.
  6. Lab <lab name> does not allow gender <gender value>: The associated lab restricts which patient genders it accepts. This restriction applies to the entire lab, not to individual lab tests.