Import Order

Create or submit order import via the Junction API. Requires authentication with your team API key.

POST /v3/order/import

Python

from junction import Billing, Gender, Junction, LabTestCollectionMethod, OrderSetRequest, PatientAddress, PatientDetailsWithValidation, PhysicianCreateRequest
from junction.environment import JunctionEnvironment

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

data = client.lab_tests.import_order(
    user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
    billing_type=Billing.CLIENT_BILL,
    order_set=OrderSetRequest(lab_test_ids=[]),
    collection_method=LabTestCollectionMethod.WALK_IN_TEST,
    physician=PhysicianCreateRequest(first_name="Jane", last_name="Doe", npi=""),
    patient_details=PatientDetailsWithValidation(
        first_name="John",
        last_name="Doe",
        dob="2020-01-01",
        gender=Gender.MALE,
        phone_number="[phone]",
        email="[e-mail]",
    ),
    patient_address=PatientAddress(
        receiver_name="John Doe",
        first_line="123 Main St.",
        second_line="Apt. 208",
        city="San Francisco",
        state="CA",
        zip="91189",
        country="US",
    ),
    sample_id="1234567890",
)

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

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

const data = await client.labTests.importOrder({
    userId: "63661a2b-2bb3-4125-bb1a-b590f64f057f",
    billingType: "client_bill",
    orderSet: {
        labTestIds: [],
    },
    collectionMethod: "walk_in_test",
    physician: {
        firstName: "Jane",
        lastName: "Doe",
        npi: "",
    },
    patientDetails: {
        firstName: "John",
        lastName: "Doe",
        dob: "2020-01-01",
        gender: "male",
        phoneNumber: "[phone]",
        email: "[e-mail]",
    },
    patientAddress: {
        receiverName: "John Doe",
        firstLine: "123 Main St.",
        secondLine: "Apt. 208",
        city: "San Francisco",
        state: "CA",
        zip: "91189",
        country: "US",
    },
    sampleId: "1234567890",
});

import com.junction.api.Junction;
import com.junction.api.core.Environment;
import com.junction.api.resources.labtests.requests.ImportOrderBody;
import com.junction.api.types.Billing;
import com.junction.api.types.Gender;
import com.junction.api.types.LabTestCollectionMethod;
import com.junction.api.types.OrderSetRequest;
import com.junction.api.types.PatientAddress;
import com.junction.api.types.PatientDetailsWithValidation;
import com.junction.api.types.PhysicianCreateRequest;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.labTests().importOrder(
    ImportOrderBody.builder()
        .userId("63661a2b-2bb3-4125-bb1a-b590f64f057f")
        .billingType(Billing.CLIENT_BILL)
        .orderSet(OrderSetRequest.builder().build())
        .collectionMethod(LabTestCollectionMethod.WALK_IN_TEST)
        .patientDetails(
            PatientDetailsWithValidation.builder()
                .firstName("John")
                .lastName("Doe")
                .dob("2020-01-01")
                .gender(Gender.MALE)
                .phoneNumber("[phone]")
                .email("[e-mail]")
                .build()
        )
        .patientAddress(
            PatientAddress.builder()
                .receiverName("John Doe")
                .firstLine("123 Main St.")
                .city("San Francisco")
                .state("CA")
                .zip("91189")
                .country("US")
                .build()
        )
        .sampleId("1234567890")
        .physician(
            PhysicianCreateRequest.builder()
                .firstName("Jane")
                .lastName("Doe")
                .npi("")
                .build()
        )
        .build()
);

import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

response, err := c.LabTests.ImportOrder(context.TODO(), &junction.ImportOrderBody{
    UserId:           "63661a2b-2bb3-4125-bb1a-b590f64f057f",
    BillingType:      junction.BillingClientBill,
    OrderSet:         &junction.OrderSetRequest{},
    CollectionMethod: junction.LabTestCollectionMethodWalkInTest,
    Physician: &junction.PhysicianCreateRequest{
        FirstName: junction.String("Jane"),
        LastName:  junction.String("Doe"),
        Npi:       "",
    },
    PatientDetails: &junction.PatientDetailsWithValidation{
        FirstName:   "John",
        LastName:    "Doe",
        Dob:         "2020-01-01",
        Gender:      junction.GenderMale,
        PhoneNumber: "[phone]",
        Email:       "[e-mail]",
    },
    PatientAddress: &junction.PatientAddress{
        ReceiverName: "John Doe",
        FirstLine:    "123 Main St.",
        SecondLine:   junction.String("Apt. 208"),
        City:         "San Francisco",
        State:        "CA",
        Zip:          "91189",
        Country:      "US",
    },
    SampleId: "1234567890",
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)

Response

{
    "order": {
        "user_id": "7ea94b27-a536-461f-ac4b-1c26c854d180",
        "id": "d3ec7ac7-2584-4254-9709-fc61d80635c4",
        "team_id": "59d4dfa1-e7c8-4d96-af15-74ca5ac5d189",
        "patient_details": {
            "first_name": "John",
            "last_name": "Doe",
            "dob": "1990-01-01T00:00:00+00:00",
            "gender": "male",
            "phone_number": "[phone]",
            "email": "[e-mail]"
        },
        "patient_address": {
            "receiver_name": "John Doe",
            "first_line": "123 Main Street",
            "second_line": null,
            "city": "New York",
            "state": "NY",
            "zip": "12345",
            "country": "US",
            "phone_number": "[phone]"
        },
        "lab_test": {
            "id": "d0b479ec-afcc-4763-985c-4e23f17149f5",
            "slug": "59d4dfa1-testosterone",
            "name": "Testosterone",
            "sample_type": "serum",
            "method": "at_home_phlebotomy",
            "price": 0.0,
            "is_active": true,
            "status": "active",
            "fasting": false,
            "lab": null,
            "markers": null,
            "is_delegated": false,
            "auto_generated": false
        },
        "details": {
            "type": "at_home_phlebotomy",
            "data": {
                "id": "21cb5e3f-25e3-443d-9fee-272de1393310",
                "appointment_id": null,
                "created_at": "2025-03-20T13:07:32+00:00",
                "updated_at": "2025-03-20T13:07:32+00:00"
            }
        },
        "sample_id": "1234567890",
        "notes": null,
        "created_at": "2025-03-20T13:07:32+00:00",
        "updated_at": "2025-03-20T13:07:32+00:00",
        "events": [
            {
                "id": 74769,
                "created_at": "2025-03-20T13:07:32+00:00",
                "status": "received.at_home_phlebotomy.ordered"
            },
            {
                "id": 74770,
                "created_at": "2025-03-20T13:07:32+00:00",
                "status": "received.at_home_phlebotomy.requisition_bypassed"
            }
        ],
        "status": "received",
        "physician": {
            "first_name": "Jane",
            "last_name": "Doe",
            "npi": "123"
        },
        "health_insurance_id": null,
        "requisition_form_url": null,
        "priority": false,
        "shipping_details": null,
        "activate_by": null,
        "passthrough": null,
        "billing_type": "client_bill",
        "icd_codes": null
    },
    "status": "success",
    "message": "Order created successfully"
}

This feature is in closed beta.

Interested in this feature? Get in touch with your Customer Success Manager.

Patient name fields (first_name, last_name) must follow specific validation rules due to lab restrictions. See Patient Name Validation for complete details.

Python

from junction import Billing, Gender, Junction, LabTestCollectionMethod, OrderSetRequest, PatientAddress, PatientDetailsWithValidation, PhysicianCreateRequest
from junction.environment import JunctionEnvironment

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

data = client.lab_tests.import_order(
    user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
    billing_type=Billing.CLIENT_BILL,
    order_set=OrderSetRequest(lab_test_ids=[]),
    collection_method=LabTestCollectionMethod.WALK_IN_TEST,
    physician=PhysicianCreateRequest(first_name="Jane", last_name="Doe", npi=""),
    patient_details=PatientDetailsWithValidation(
        first_name="John",
        last_name="Doe",
        dob="2020-01-01",
        gender=Gender.MALE,
        phone_number="[phone]",
        email="[e-mail]",
    ),
    patient_address=PatientAddress(
        receiver_name="John Doe",
        first_line="123 Main St.",
        second_line="Apt. 208",
        city="San Francisco",
        state="CA",
        zip="91189",
        country="US",
    ),
    sample_id="1234567890",
)

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

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

const data = await client.labTests.importOrder({
    userId: "63661a2b-2bb3-4125-bb1a-b590f64f057f",
    billingType: "client_bill",
    orderSet: {
        labTestIds: [],
    },
    collectionMethod: "walk_in_test",
    physician: {
        firstName: "Jane",
        lastName: "Doe",
        npi: "",
    },
    patientDetails: {
        firstName: "John",
        lastName: "Doe",
        dob: "2020-01-01",
        gender: "male",
        phoneNumber: "[phone]",
        email: "[e-mail]",
    },
    patientAddress: {
        receiverName: "John Doe",
        firstLine: "123 Main St.",
        secondLine: "Apt. 208",
        city: "San Francisco",
        state: "CA",
        zip: "91189",
        country: "US",
    },
    sampleId: "1234567890",
});

import com.junction.api.Junction;
import com.junction.api.core.Environment;
import com.junction.api.resources.labtests.requests.ImportOrderBody;
import com.junction.api.types.Billing;
import com.junction.api.types.Gender;
import com.junction.api.types.LabTestCollectionMethod;
import com.junction.api.types.OrderSetRequest;
import com.junction.api.types.PatientAddress;
import com.junction.api.types.PatientDetailsWithValidation;
import com.junction.api.types.PhysicianCreateRequest;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.labTests().importOrder(
    ImportOrderBody.builder()
        .userId("63661a2b-2bb3-4125-bb1a-b590f64f057f")
        .billingType(Billing.CLIENT_BILL)
        .orderSet(OrderSetRequest.builder().build())
        .collectionMethod(LabTestCollectionMethod.WALK_IN_TEST)
        .patientDetails(
            PatientDetailsWithValidation.builder()
                .firstName("John")
                .lastName("Doe")
                .dob("2020-01-01")
                .gender(Gender.MALE)
                .phoneNumber("[phone]")
                .email("[e-mail]")
                .build()
        )
        .patientAddress(
            PatientAddress.builder()
                .receiverName("John Doe")
                .firstLine("123 Main St.")
                .city("San Francisco")
                .state("CA")
                .zip("91189")
                .country("US")
                .build()
        )
        .sampleId("1234567890")
        .physician(
            PhysicianCreateRequest.builder()
                .firstName("Jane")
                .lastName("Doe")
                .npi("")
                .build()
        )
        .build()
);

import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

response, err := c.LabTests.ImportOrder(context.TODO(), &junction.ImportOrderBody{
    UserId:           "63661a2b-2bb3-4125-bb1a-b590f64f057f",
    BillingType:      junction.BillingClientBill,
    OrderSet:         &junction.OrderSetRequest{},
    CollectionMethod: junction.LabTestCollectionMethodWalkInTest,
    Physician: &junction.PhysicianCreateRequest{
        FirstName: junction.String("Jane"),
        LastName:  junction.String("Doe"),
        Npi:       "",
    },
    PatientDetails: &junction.PatientDetailsWithValidation{
        FirstName:   "John",
        LastName:    "Doe",
        Dob:         "2020-01-01",
        Gender:      junction.GenderMale,
        PhoneNumber: "[phone]",
        Email:       "[e-mail]",
    },
    PatientAddress: &junction.PatientAddress{
        ReceiverName: "John Doe",
        FirstLine:    "123 Main St.",
        SecondLine:   junction.String("Apt. 208"),
        City:         "San Francisco",
        State:        "CA",
        Zip:          "91189",
        Country:      "US",
    },
    SampleId: "1234567890",
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)

Response

{
    "order": {
        "user_id": "7ea94b27-a536-461f-ac4b-1c26c854d180",
        "id": "d3ec7ac7-2584-4254-9709-fc61d80635c4",
        "team_id": "59d4dfa1-e7c8-4d96-af15-74ca5ac5d189",
        "patient_details": {
            "first_name": "John",
            "last_name": "Doe",
            "dob": "1990-01-01T00:00:00+00:00",
            "gender": "male",
            "phone_number": "[phone]",
            "email": "[e-mail]"
        },
        "patient_address": {
            "receiver_name": "John Doe",
            "first_line": "123 Main Street",
            "second_line": null,
            "city": "New York",
            "state": "NY",
            "zip": "12345",
            "country": "US",
            "phone_number": "[phone]"
        },
        "lab_test": {
            "id": "d0b479ec-afcc-4763-985c-4e23f17149f5",
            "slug": "59d4dfa1-testosterone",
            "name": "Testosterone",
            "sample_type": "serum",
            "method": "at_home_phlebotomy",
            "price": 0.0,
            "is_active": true,
            "status": "active",
            "fasting": false,
            "lab": null,
            "markers": null,
            "is_delegated": false,
            "auto_generated": false
        },
        "details": {
            "type": "at_home_phlebotomy",
            "data": {
                "id": "21cb5e3f-25e3-443d-9fee-272de1393310",
                "appointment_id": null,
                "created_at": "2025-03-20T13:07:32+00:00",
                "updated_at": "2025-03-20T13:07:32+00:00"
            }
        },
        "sample_id": "1234567890",
        "notes": null,
        "created_at": "2025-03-20T13:07:32+00:00",
        "updated_at": "2025-03-20T13:07:32+00:00",
        "events": [
            {
                "id": 74769,
                "created_at": "2025-03-20T13:07:32+00:00",
                "status": "received.at_home_phlebotomy.ordered"
            },
            {
                "id": 74770,
                "created_at": "2025-03-20T13:07:32+00:00",
                "status": "received.at_home_phlebotomy.requisition_bypassed"
            }
        ],
        "status": "received",
        "physician": {
            "first_name": "Jane",
            "last_name": "Doe",
            "npi": "123"
        },
        "health_insurance_id": null,
        "requisition_form_url": null,
        "priority": false,
        "shipping_details": null,
        "activate_by": null,
        "passthrough": null,
        "billing_type": "client_bill",
        "icd_codes": null
    },
    "status": "success",
    "message": "Order created successfully"
}

Authorizations

x-vital-api-key · string · header · required

Vital Team API Key

Body

application/json

user_id · string<uuid> · required

billing_type · enum<string> · required

ℹ️ This enum is non-exhaustive.

Available options: client_bill, commercial_insurance, patient_bill_passthrough, patient_bill

order_set · OrderSetRequest · object · required

Show child attributes

collection_method · enum<string> · required

ℹ️ This enum is non-exhaustive.

Available options: testkit, walk_in_test, at_home_phlebotomy, on_site_collection

patient_details · PatientDetailsWithValidation · object · required

Patient details with validation for first_name, last_name, email, and dob.

Show child attributes

patient_address · PatientAddress · object · required

Show child attributes

sample_id · string · required

physician · PhysicianCreateRequest · object | null

Show child attributes

lab_account_id · string<uuid> | null

Response

200

application/json

Successful Response

order · ClientFacingOrder · object · required

Show child attributes

Example:

{
  "activate_by": "2020-01-01",
  "created_at": "2020-01-01T00:00:00Z",
  "details": {
    "data": {
      "created_at": "2020-01-01T00:00:00Z",
      "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
      "shipment": {
        "created_at": "2020-01-01T00:00:00.000Z",
        "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
        "inbound_courier": "usps",
        "inbound_tracking_number": "<inbound_tracking_number>",
        "inbound_tracking_url": "<inbound_tracking_url>",
        "notes": "<notes>",
        "outbound_courier": "usps",
        "outbound_tracking_number": "<outbound_tracking_number>",
        "outbound_tracking_url": "<outbound_tracking_url>",
        "updated_at": "2020-01-01T00:00:00.000Z"
      },
      "updated_at": "2020-01-01T00:00:00Z"
    },
    "type": "testkit"
  },
  "events": [
    {
      "created_at": "2022-01-01T00:00:00Z",
      "id": 1,
      "status": "received.testkit.ordered"
    },
    {
      "created_at": "2022-01-02T00:00:00Z",
      "id": 2,
      "status": "received.testkit.requisition_created"
    },
    {
      "created_at": "2022-01-03T00:00:00Z",
      "id": 3,
      "status": "collecting_sample.testkit.transit_customer"
    }
  ],
  "has_abn": false,
  "health_insurace_id": "67f14813-2762-4a6e-8b6a-82e45502671c",
  "id": "6982d7b2-b36c-4781-8e76-9c6858e648a7",
  "lab_test": {
    "description": "Cholesterol test",
    "method": "testkit",
    "name": "Lipids Panel"
  },
  "last_event": {
    "created_at": "2022-01-03T00:00:00Z",
    "id": 3,
    "status": "collecting_sample.testkit.transit_customer"
  },
  "notes": "This is a note",
  "order_transaction": {
    "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
    "orders": [
      {
        "created_at": "2020-01-01T00:00:00Z",
        "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
        "low_level_status": "transit_customer",
        "low_level_status_created_at": "2020-01-05T00:00:00Z",
        "origin": "initial",
        "updated_at": "2020-01-05T00:00:00Z"
      },
      {
        "created_at": "2020-01-05T01:00:00Z",
        "id": "e66321dd-4e0g-5226-9373-6124g811d8cf",
        "low_level_status": "requisition_created",
        "low_level_status_created_at": "2020-01-05T01:00:00Z",
        "origin": "redraw",
        "updated_at": "2020-01-05T01:00:00Z"
      }
    ],
    "status": "active"
  },
  "origin": "initial",
  "patient_address": {
    "city": "San Francisco",
    "country": "United States",
    "first_line": "123 Main St.",
    "phone_number": "[phone]",
    "receiver_name": "John Doe",
    "second_line": "Apt. 208",
    "state": "CA",
    "zip": "91189"
  },
  "patient_details": { "dob": "2020-01-01", "gender": "male" },
  "requisition_form_url": "https://www.example.com",
  "sample_id": "123456789",
  "status": "collecting_sample",
  "team_id": "85b88076-494d-4801-a81f-b5f7893c482e",
  "updated_at": "2020-01-01T00:00:00Z",
  "user_id": "880f9f9f-2818-414b-9baa-ef36ded302c2"
}

status · string · required

message · string · required