Choosing Tests and Markers

Use the order_set field when you create an order to define the tests and markers the laboratory should perform. You can reference reusable lab tests, select markers directly from the compendium, or combine both approaches.

Approach	Use when
One saved lab test	You repeatedly order a predefined set of markers.
Multiple saved lab tests	You need to combine compatible saved definitions for one order.
À la carte markers	You need a one-off selection without creating a saved lab test.
Saved lab test with add-ons	You need a standard definition plus patient-specific markers.

Understand tests and markers

Markers

Markers are the individual items a partner laboratory makes available to order. A marker can represent a single biomarker or a laboratory-defined panel. For example, Junction represents both a vitamin D test and a lipid panel as markers.

Lab tests

Lab tests are reusable definitions that contain one or more markers. Create a lab test when your program repeatedly orders the same combination. When you place an order, reference the lab test’s id in order_set.lab_test_ids.

Choose what to order

Choose the order_set combination that matches how your integration manages reusable test definitions.

Use one saved lab test

Reference one previously created lab test when the same marker set is used repeatedly:

from junction import Junction, OrderSetRequest
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

client.lab_tests.create_order(
    order_set=OrderSetRequest(
        lab_test_ids=["<lab_test_id>"],
    ),
    # ...
)

Combine saved lab tests

Reference two or more compatible lab tests when you want to combine their markers without creating another reusable definition:

from junction import Junction, OrderSetRequest
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

client.lab_tests.create_order(
    order_set=OrderSetRequest(
        lab_test_ids=["<lab_test_id_1>", "<lab_test_id_2>"],
    ),
    # ...
)

Choose markers à la carte

Use à la carte ordering to select markers from the compendium without first creating a lab test.

À la carte ordering is generally available to all Teams, but not every marker supports it. See Find markers available à la carte.

Identify the markers with either Junction marker_ids or the partner laboratory’s provider_ids. Do not provide both identifier types in the same add_on object.

from junction import AddOnOrder, Junction, LabTestCollectionMethod, OrderSetRequest
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

client.lab_tests.create_order(
    order_set=OrderSetRequest(
        add_on=AddOnOrder(
            provider_ids=["322022"],
            # marker_ids=[1],
        ),
    ),
    collection_method=LabTestCollectionMethod.WALK_IN_TEST,
    # ...
)

Add markers to a saved lab test

Use add_on with lab_test_ids when an order needs a reusable lab test plus patient-specific markers.

from junction import AddOnOrder, Junction, LabTestCollectionMethod, OrderSetRequest
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

client.lab_tests.create_order(
    order_set=OrderSetRequest(
        lab_test_ids=["<lab_test_id>"],
        add_on=AddOnOrder(
            provider_ids=["322022"],
            # marker_ids=[1],
        ),
    ),
    collection_method=LabTestCollectionMethod.WALK_IN_TEST,
    # ...
)

When you provide add_on, you must also provide collection_method.

Choose a collection method

Junction supports four collection methods: Mobile Phlebotomy, Walk-in, At-home Test Kits, and On-site Collection. The collection method can come from the saved lab test or from collection_method in the order request. Provide it in the order request when the selected lab tests do not resolve to one collection method or when using add_on.

from junction import Junction, LabTestCollectionMethod, OrderSetRequest
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

client.lab_tests.create_order(
    order_set=OrderSetRequest(
        lab_test_ids=["<lab_test_id>"],
    ),
    collection_method=LabTestCollectionMethod.WALK_IN_TEST,
    # ...
)

At-Home Phlebotomy Auto-Approval

This feature is in closed beta.Interested in this feature? Get in touch with your Customer Success Manager.

This beta applies only to auto-approval of at-home phlebotomy tests. When ordering without a Lab Test, this is subject to the same auto-approval validation as POST /v3/lab_tests. For eligible teams and labs, this validation is successful when:

Collection Instructions are available for every marker.
Every marker is enabled for à la carte ordering, if your team does not use a delegated flow.
The estimated draw is fewer than 15 tubes. An estimate of 15 tubes or more is rejected.

A referenced lab test must be active. A pending at-home phlebotomy test that was created before auto-evaluation applied to the current team can return HTTP 400 when ordered.

Find markers available à la carte

Not every marker can be ordered à la carte. Use Get Markers with the a_la_carte_enabled filter to find supported markers.

from junction import Junction
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.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")

Test-selection errors

The API validates the selected tests, markers, laboratories, and collection methods before accepting an order.

400 Bad Request

collection_method must be set if add_on is set: Include collection_method whenever you provide add_on.
marker_ids or provider_ids must be set in add_on: Include one marker identifier type in add_on.
cannot set both marker_ids and provider_ids in add_on: Use either Junction marker IDs or provider IDs, not both.
cannot order lab_tests from multiple labs: All referenced lab tests must belong to the same partner laboratory.
cannot order lab tests with multiple collection methods: Provide one compatible collection_method when combining lab tests.
test is not active: A referenced lab test is still pending approval or otherwise inactive. It cannot be ordered until its status is active.

Getting Started

Ordering Workflows

Walk-in (Patient Service Center) Orders

Mobile Phlebotomy Orders

At-Home Test Kit Orders

On-site Collection Orders

Results and Follow-up

Lab Report Parsing

Choosing Tests and Markers

Understand tests and markers

Markers

Lab tests

Choose what to order

Use one saved lab test

Combine saved lab tests

Choose markers à la carte

Add markers to a saved lab test

Choose a collection method

At-Home Phlebotomy Auto-Approval

Find markers available à la carte

Test-selection errors

400 Bad Request

​Understand tests and markers

​Markers

​Lab tests

​Choose what to order

​Use one saved lab test

​Combine saved lab tests

​Choose markers à la carte

​Add markers to a saved lab test

​Choose a collection method

​At-Home Phlebotomy Auto-Approval

​Find markers available à la carte

​Test-selection errors

​400 Bad Request

​Related guides

Understand tests and markers

Markers

Lab tests

Choose what to order

Use one saved lab test

Combine saved lab tests

Choose markers à la carte

Add markers to a saved lab test

Choose a collection method

At-Home Phlebotomy Auto-Approval

Find markers available à la carte

Test-selection errors

400 Bad Request

Related guides