Skip to main content
An order represents one unit of laboratory work for a patient. An order transaction represents the broader testing journey and groups the initial order with any related orders. Use this guide to understand how those objects progress from order creation to results. For a runnable sandbox example, start with the Quickstart.

​
Integration flow

1

Configure the ordering workflow

Choose a testing modality, then decide which tests and markers the order should include. Confirm the required lab account and billing type, physician workflow, and patient information before creating a production order.
2

Create the patient and order

Create or identify the Junction user representing the patient, then call Create Order. Use an idempotency key so a safe retry does not create a duplicate order.Creating an initial order also creates its order transaction. Store the returned order.id and order_transaction.id. Use the order transaction ID as the stable grouping key for the testing journey and retain each order ID for order-specific operations.
3

Monitor the order and transaction

Subscribe to labtest.order.updated and the result events required by your workflow. Treat webhooks as notifications that data changed, then retrieve the current order before making a final workflow decision.Use order.status and order.events to track the operational progress of an individual order. Use order_transaction.status to determine whether the broader testing journey is still active, completed, or cancelled. If a related order is created, keep it grouped under the same transaction ID. See Order Status and Lifecycle, Order Transactions, and the guide for the order’s testing modality.
4

Retrieve results

When the order transaction reaches completed, call Get Order Transaction Results to retrieve the complete structured result across its orders. Retrieve the order transaction results PDF when the combined laboratory report is required and available.Use Get Order Results and the order result PDF when you specifically need results for one order. Some results are available while an order is still in progress. If your workflow uses them, handle partial results separately and do not present them as final. See Results Overview for the recommended retrieval flow.
5

Handle follow-up states

Plan for critical results, redraws, and unmatched results when those workflows apply to your integration. If Junction’s physician network supports the order, physician follow-up may apply to abnormal results.

​
How the objects relate

For example, a supported redraw creates another order in the original order transaction. The initial and redraw orders retain separate statuses and results, while the transaction provides their combined result.

​
Identifiers to store

The sample_id may not be available when the order is first created. Store it when it appears on the order. Store your own patient and request identifiers alongside the Junction identifiers so webhook processing and operational support can reconcile records across systems.

​
Order, transaction, and result status

Order, transaction, and result statuses answer different questions:
  • order.status describes the operational state of one order, such as received, collecting_sample, sample_with_lab, or completed.
  • order_transaction.status describes whether the full testing journey is active, completed, or cancelled.
  • result.status describes whether the laboratory findings are partial or final.
A partial result can be available while an order and its transaction are still active. When the transaction reaches completed, retrieve the combined transaction result rather than treating an order webhook as the result payload.

​
Integration requirements

  • Make webhook processing idempotent because delivery can be retried or arrive out of order.
  • Treat unknown order and result enum values gracefully so newly introduced values do not break the integration.
  • Use the API as the source of truth for current order, transaction, and result state rather than relying on webhook delivery order.
  • Test lifecycle transitions and result handling in the sandbox environment before placing production orders.