Orders
Import Order
Orders
At-home Phlebotomy
Patient Service Center (PSC)
Tests
Health Insurance
Orders
Import Order
POST
/
v3
/
order
/
import
from vital.client import Vital
from vital.environment import VitalEnvironment
from vital.types.billing import Billing
from vital.types.gender import Gender
from vital.types.lab_test_collection_method import LabTestCollectionMethod
from vital.types.order_set_request import OrderSetRequest
from vital.types.patient_address_compatible import PatientAddressCompatible
from vital.types.patient_details import PatientDetails
from vital.types.physician_create_request import PhysicianCreateRequest
from datetime import datetime
client = Vital(
api_key="YOUR_API_KEY",
environment=VitalEnvironment.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=PatientDetails(
first_name="John",
last_name="Doe",
dob=datetime.fromisoformat("2020-01-01"),
gender=Gender.MALE,
phone_number="+1123456789",
email="email@email.com"
),
patient_address=PatientAddressCompatible(
receiver_name="John Doe",
first_line="123 Main St.",
second_line="Apt. 208",
city="San Francisco",
state="CA",
zip="91189",
country="US",
phone_number="+1123456789"
),
sample_id="1234567890",
)
{
"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": "+11231234123",
"email": "john@example.com"
},
"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": "+11231234123"
},
"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.
from vital.client import Vital
from vital.environment import VitalEnvironment
from vital.types.billing import Billing
from vital.types.gender import Gender
from vital.types.lab_test_collection_method import LabTestCollectionMethod
from vital.types.order_set_request import OrderSetRequest
from vital.types.patient_address_compatible import PatientAddressCompatible
from vital.types.patient_details import PatientDetails
from vital.types.physician_create_request import PhysicianCreateRequest
from datetime import datetime
client = Vital(
api_key="YOUR_API_KEY",
environment=VitalEnvironment.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=PatientDetails(
first_name="John",
last_name="Doe",
dob=datetime.fromisoformat("2020-01-01"),
gender=Gender.MALE,
phone_number="+1123456789",
email="email@email.com"
),
patient_address=PatientAddressCompatible(
receiver_name="John Doe",
first_line="123 Main St.",
second_line="Apt. 208",
city="San Francisco",
state="CA",
zip="91189",
country="US",
phone_number="+1123456789"
),
sample_id="1234567890",
)
{
"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": "+11231234123",
"email": "john@example.com"
},
"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": "+11231234123"
},
"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
Vital Team API Key
Body
application/json
ℹ️ This enum is non-exhaustive.
Available options:
client_bill, commercial_insurance, patient_bill_passthrough, patient_bill The method used to perform a lab test. ℹ️ This enum is non-exhaustive.
Available options:
testkit, walk_in_test, at_home_phlebotomy Patient details with validation for first_name, last_name, email, and dob.
Required string length:
1 - 50Required string length:
1 - 50ℹ️ This enum is non-exhaustive.
Available options:
female, male, other, unknown Parent/medical_proxy details. Required if patient is a minor.
If not provided, will be set to 'Not Specified'
Available options:
african_american_or_black, asian, indigenous_native_american_alaska_native, other, pacific_islander_or_hawaiian, white_caucasian If not provided, will be set to 'Not Specified'
Available options:
hispanic, non_hispanic, ashkenazi_jewish, other If not provided, will be set to 'Not Specified'
Available options:
lesbian_gay_or_homosexual, heterosexual_or_straight, bisexual, dont_know, other If not provided, will be set to 'Not Specified'
Available options:
male, female, female_to_male_ftm_transgender_male_trans_man, male_to_female_mtf_transgender_female_trans_woman, genderqueer, other Response
200
application/json
Successful Response
User id returned by vital create user request. This id should be stored in your database against the user and used for all interactions with the vital api.
The Vital Order ID
Your team id.
Patient Details
Parent/medical_proxy details. Required if patient is a minor.
If not provided, will be set to 'Not Specified'
Available options:
african_american_or_black, asian, indigenous_native_american_alaska_native, other, pacific_islander_or_hawaiian, white_caucasian If not provided, will be set to 'Not Specified'
Available options:
hispanic, non_hispanic, ashkenazi_jewish, other If not provided, will be set to 'Not Specified'
Available options:
lesbian_gay_or_homosexual, heterosexual_or_straight, bisexual, dont_know, other If not provided, will be set to 'Not Specified'
Available options:
male, female, female_to_male_ftm_transgender_male_trans_man, male_to_female_mtf_transgender_female_trans_woman, genderqueer, other Patient Address
The Vital Test associated with the order
Available options:
dried_blood_spot, arm_collector, serum, saliva, urine Available options:
testkit, walk_in_test, at_home_phlebotomy Deprecated. Use status instead.
Available options:
active, pending_approval, inactive The method used to perform a lab test. ℹ️ This enum is non-exhaustive.
Available options:
testkit, walk_in_test, at_home_phlebotomy The type of sample used to perform a lab test. ℹ️ This enum is non-exhaustive.
Available options:
dried_blood_spot, arm_collector, serum, saliva, urine Example:
{
"city": "San Francisco",
"collection_methods": ["testkit"],
"first_line_address": "123 Main St",
"id": 1,
"name": "LabCorp",
"sample_types": ["saliva"],
"slug": "labcorp",
"zipcode": "91789"
}
ℹ️ This enum is non-exhaustive.
Available options:
biomarker, panel Defines whether a lab test requires fasting.
Denotes whether a lab test requires using non-Vital physician networks. If it does then it's delegated - no otherwise.
Whether the lab test was auto-generated by Vital
Example:
{
"lab_test": {
"description": "Cholesterol test",
"fasting": false,
"is_delegated": false,
"lab": {
"city": "New York",
"first_line_address": "123 Main St",
"name": "US Specialty Lab",
"slug": "USSL",
"zipcode": "10001"
},
"markers": [
{
"description": "Hemoglobin A1c is a form of hemoglobin that is measured identify your average blood sugar levels over the past 3 months.",
"id": 1,
"lab_id": 1,
"name": "Hemoglobin A1c",
"price": "10.00",
"provider_id": "1234",
"slug": "hemoglobin-a1c",
"type": "biomarker",
"unit": "%"
}
],
"method": "testkit",
"name": "Lipids Panel",
"price": 10,
"sample_type": "dried blood spot",
"status": "active"
}
}
Allowed value:
"walk_in_test"Schema for a walk-in test order in the client facing API.
To be used as part of a ClientFacingOrder.
Example:
{
"appointment_id": "ba72deb6-74dd-4db7-99c2-e57c969c7c16",
"created_at": "2020-01-01T00:00:00Z",
"id": "1f69ce6a-e21c-445a-91f7-9803c8460495",
"updated_at": "2020-01-01T00:00:00Z"
}
Sample ID
Notes associated with the order
When your order was created
When your order was last updated.
ℹ️ This enum is non-exhaustive.
Available options:
received.walk_in_test.ordered, received.walk_in_test.requisition_created, received.walk_in_test.requisition_bypassed, completed.walk_in_test.completed, sample_with_lab.walk_in_test.partial_results, failed.walk_in_test.sample_error, cancelled.walk_in_test.cancelled, collecting_sample.walk_in_test.appointment_pending, collecting_sample.walk_in_test.appointment_scheduled, collecting_sample.walk_in_test.appointment_cancelled, received.at_home_phlebotomy.ordered, received.at_home_phlebotomy.requisition_created, received.at_home_phlebotomy.requisition_bypassed, collecting_sample.at_home_phlebotomy.appointment_pending, collecting_sample.at_home_phlebotomy.appointment_scheduled, collecting_sample.at_home_phlebotomy.draw_completed, collecting_sample.at_home_phlebotomy.appointment_cancelled, completed.at_home_phlebotomy.completed, sample_with_lab.at_home_phlebotomy.partial_results, cancelled.at_home_phlebotomy.cancelled, failed.at_home_phlebotomy.sample_error, received.testkit.ordered, received.testkit.awaiting_registration, received.testkit.requisition_created, received.testkit.requisition_bypassed, received.testkit.registered, collecting_sample.testkit.transit_customer, collecting_sample.testkit.out_for_delivery, collecting_sample.testkit.with_customer, collecting_sample.testkit.transit_lab, sample_with_lab.testkit.delivered_to_lab, completed.testkit.completed, failed.testkit.failure_to_deliver_to_customer, failed.testkit.failure_to_deliver_to_lab, failed.testkit.sample_error, failed.testkit.lost, cancelled.testkit.cancelled, cancelled.testkit.do_not_process, collecting_sample.testkit.problem_in_transit_customer, collecting_sample.testkit.problem_in_transit_lab Vital ID of the health insurance.
DEPRECATED. Requistion form url.
Shipping Details. For unregistered testkit orders.
Defines whether the order has an Advanced Beneficiary Notice (ABN) form or not.
ℹ️ This enum is non-exhaustive.
Available options:
received, collecting_sample, sample_with_lab, completed, cancelled, failed Defines whether order is priority or not. For some labs, this refers to a STAT order.
Schedule an Order to be processed in a future date.
ℹ️ This enum is non-exhaustive.
Available options:
client_bill, commercial_insurance, patient_bill_passthrough, patient_bill 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": "588f338a-9472-47fa-8ba8-76fa6bc5f648",
"id": "d54f0790-452d-4238-a55e-ca0b7970b25e",
"lab_test": {
"description": "Cholesterol test",
"method": "testkit",
"name": "Lipids Panel"
},
"notes": "This is a note",
"patient_address": {
"city": "San Francisco",
"country": "United States",
"first_line": "123 Main St.",
"phone_number": "+11234567890",
"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": "7d0a12e8-3442-4d32-a2f8-08ce0b022f12",
"updated_at": "2020-01-01T00:00:00Z",
"user_id": "d41dce42-e16a-43d2-b2f1-f1eb032d75c9"
}
from vital.client import Vital
from vital.environment import VitalEnvironment
from vital.types.billing import Billing
from vital.types.gender import Gender
from vital.types.lab_test_collection_method import LabTestCollectionMethod
from vital.types.order_set_request import OrderSetRequest
from vital.types.patient_address_compatible import PatientAddressCompatible
from vital.types.patient_details import PatientDetails
from vital.types.physician_create_request import PhysicianCreateRequest
from datetime import datetime
client = Vital(
api_key="YOUR_API_KEY",
environment=VitalEnvironment.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=PatientDetails(
first_name="John",
last_name="Doe",
dob=datetime.fromisoformat("2020-01-01"),
gender=Gender.MALE,
phone_number="+1123456789",
email="email@email.com"
),
patient_address=PatientAddressCompatible(
receiver_name="John Doe",
first_line="123 Main St.",
second_line="Apt. 208",
city="San Francisco",
state="CA",
zip="91189",
country="US",
phone_number="+1123456789"
),
sample_id="1234567890",
)
{
"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": "+11231234123",
"email": "john@example.com"
},
"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": "+11231234123"
},
"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"
}