Configuring Lab Orders

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.

Fasting requirement

Set order_set.parameters.fasting in the Create Order request to override the fasting requirement for the order. It applies to saved lab tests (lab_test_ids), à la carte markers (add_on), and combinations of both. This parameter specifies whether fasting is required before sample collection. It does not record whether the patient has actually fasted.

Value	Behavior
`"fasting_required"`	Require fasting for this order, regardless of the selected lab tests’ fasting settings.
`"fasting_not_required"`	Do not require fasting for this order, regardless of the selected lab tests’ fasting settings.
Omitted or `null`	Use the default behavior described below.

When you omit the parameter or set it to null:

With lab_test_ids only, fasting is required if any selected lab test requires it. For a single lab test, its fasting setting is preserved.
With add_on, fasting is required by default, including when you also provide lab_test_ids.

Use order_set.lab_test_ids instead of the top-level lab_test_id when supplying this parameter. For example, include the following order_set in your create-order request to order a saved lab test without requiring fasting:

{
  "order_set": {
    "lab_test_ids": ["5b41f610-ebc5-4803-8f0c-a61c3bdc7faf"],
    "parameters": {
      "fasting": "fasting_not_required"
    }
  }
}

For à la carte ordering, place parameters alongside add_on inside order_set. Include collection_method, which is required whenever you use add_on. For example, include these fields in your create-order request to order an à la carte marker without requiring fasting:

{
  "collection_method": "walk_in_test",
  "order_set": {
    "add_on": {
      "provider_ids": ["322022"]
    },
    "parameters": {
      "fasting": "fasting_not_required"
    }
  }
}

The same override works when using add_on.marker_ids instead of add_on.provider_ids, or when combining add_on with lab_test_ids. The override applies to the lab test used for this order. It does not change your saved lab tests, and normal test approval and ordering requirements still apply.

Explicit fasting answers supplied in aoe_answers take precedence over the lab test’s effective fasting setting for the corresponding Ask on Order Entry (AOE) question. If you do not supply a fasting answer, Junction uses the effective fasting setting, including any override from order_set.parameters.fasting.

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

Configuring Lab Orders

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

Fasting requirement

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

​Fasting requirement

​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

Fasting requirement

Find markers available à la carte

Test-selection errors

400 Bad Request

Related guides