Quickstart

This guide creates a patient and places a lab order in the sandbox environment.

Prerequisites

A sandbox Team and API key from the Junction Dashboard. See API Keys.
Your sandbox base URL.
An HTTP client or a supported Junction SDK.

The examples use {{BASE_URL}} for your sandbox base URL and YOUR_API_KEY for your Team API key. The API key header remains x-vital-api-key.

1. Create a patient

In the Junction API, a user represents a patient. Set client_user_id to the stable identifier your system uses for that patient.

curl --request POST \
  --url '{{BASE_URL}}/v2/user' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-vital-api-key: YOUR_API_KEY' \
  --data '{"client_user_id":"patient-123"}'

from junction import Junction
from junction.environment import JunctionEnvironment

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

user = client.user.create(client_user_id="patient-123")

import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

const client = new JunctionClient({
  apiKey: "YOUR_API_KEY",
  environment: JunctionEnvironment.Sandbox,
});

const user = await client.user.create({ clientUserId: "patient-123" });

Save the returned user id. You will provide it as user_id when creating the order. See Create User for the complete request and response.

2. Select a lab test

Retrieve the lab tests available to your sandbox Team:

curl --request GET \
  --url '{{BASE_URL}}/v3/lab_test' \
  --header 'Accept: application/json' \
  --header 'x-vital-api-key: YOUR_API_KEY'

lab_tests = client.lab_tests.get_paginated()

const labTests = await client.labTests.getPaginated();

Select a test that supports the collection method you want to exercise and save its id. See Get Available Tests for filters and pagination.

Sandbox Teams include tests for the standard collection modalities. You can also create a custom lab test when you need a specific marker set.

3. Create the order

Provide the patient ID, select the lab test in order_set, and include the patient’s demographics and collection address. Patient names must meet the patient name requirements.

curl --request POST \
  --url '{{BASE_URL}}/v3/order' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-vital-api-key: YOUR_API_KEY' \
  --data '{
    "user_id": "YOUR_USER_ID",
    "order_set": {
      "lab_test_ids": ["YOUR_LAB_TEST_ID"]
    },
    "patient_details": {
      "first_name": "John",
      "last_name": "Doe",
      "dob": "1990-01-01",
      "gender": "male",
      "phone_number": "+11234567890",
      "email": "patient@example.com"
    },
    "patient_address": {
      "receiver_name": "John Doe",
      "first_line": "256 West Lincoln Street",
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85004",
      "country": "US",
      "phone_number": "+11234567890"
    }
  }'

from junction import Gender, OrderSetRequest, PatientAddressWithValidation, PatientDetailsWithValidation

order = client.lab_tests.create_order(
    user_id="YOUR_USER_ID",
    order_set=OrderSetRequest(
        lab_test_ids=["YOUR_LAB_TEST_ID"],
    ),
    patient_details=PatientDetailsWithValidation(
        first_name="John",
        last_name="Doe",
        dob="1990-01-01",
        gender=Gender.MALE,
        phone_number="+11234567890",
        email="patient@example.com",
    ),
    patient_address=PatientAddressWithValidation(
        receiver_name="John Doe",
        first_line="256 West Lincoln Street",
        city="Phoenix",
        state="AZ",
        zip="85004",
        country="US",
        phone_number="+11234567890",
    ),
)

const order = await client.labTests.createOrder({
  userId: "YOUR_USER_ID",
  orderSet: {
    labTestIds: ["YOUR_LAB_TEST_ID"],
  },
  patientDetails: {
    firstName: "John",
    lastName: "Doe",
    dob: "1990-01-01",
    gender: "male",
    phoneNumber: "+11234567890",
    email: "patient@example.com",
  },
  patientAddress: {
    receiverName: "John Doe",
    firstLine: "256 West Lincoln Street",
    city: "Phoenix",
    state: "AZ",
    zip: "85004",
    country: "US",
    phoneNumber: "+11234567890",
  },
});

The response contains the new order under order. Creating this initial order also creates an order transaction representing the full testing journey. Save order.id and order_transaction.id: use the order ID for order-specific operations and the transaction ID to group the initial order with any related orders and retrieve their combined results. Inspect order.status and order.events as the individual order progresses. See Create Order for all ordering options.

4. Test the order workflow

Sandbox orders remain in their initial state until you simulate their progression. Use the Junction Dashboard or the Simulate Order endpoint, then verify that your integration receives the expected webhook events. See Testing in Sandbox for supported simulations, modality-specific test data, and result customization.

Next steps

Learn how order statuses work in Order Status and Lifecycle.
Learn how related orders and combined results work in Order Transactions.
Review the workflow for the order’s testing modality.
Configure patient communications if Junction should contact the patient.
Continue through the integration lifecycle with Orders and Results.

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

Prerequisites

1. Create a patient

2. Select a lab test

3. Create the order

4. Test the order workflow

Next steps

​Prerequisites

​1. Create a patient

​2. Select a lab test

​3. Create the order

​4. Test the order workflow

​Next steps

Prerequisites

1. Create a patient

2. Select a lab test

3. Create the order

4. Test the order workflow

Next steps