Skip to main content
POST
/
v3
/
order
from vital.client import Vital
from vital.environment import VitalEnvironment
from vital.types.gender import Gender
from vital.types.patient_address_compatible import PatientAddressCompatible
from vital.types.patient_details import PatientDetails
from datetime import datetime

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

data = client.lab_tests.create_order(
    user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
    lab_test_id="5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
    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"
    ),
)

{
   "order": {
      "id": "ea7eae96-2c25-404f-b043-bfc08584610d",
      "team_id": "c26a9cc7-cdff-4f23-a5f6-74d40088c16a",
      "user_id": "63661a2b-2bb3-4125-bb1a-b590f64f057f",
      "patient_details": {
         "dob": "2020-01-01",
         "gender": "male"
      },
      "patient_address": {
         "receiver_name": "John Doe",
         "first_line": "123 Main St.",
         "second_line": "Apt. 208",
         "city": "San Francisco",
         "state": "CA",
         "zip": "91189",
         "country": "United States",
         "phone_number": "+1123456789"
      },
      "priority": false,
      "health_insurance_id": "33ec11aa-d8bf-4f46-950d-c9171be3c22f",
      "details": {
         "type": "testkit",
         "data": {
         "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
         "shipment": {
            "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
            "outbound_tracking_number": "<outbound_tracking_number>",
            "outbound_tracking_url": "<outbound_tracking_url>",
            "inbound_tracking_number": "<inbound_tracking_number>",
            "inbound_tracking_url": "<inbound_tracking_url>",
            "outbound_courier": "usps",
            "inbound_courier": "usps",
            "notes": "<notes>",
            "created_at": "2020-01-01T00:00:00.000Z",
            "updated_at": "2020-01-01T00:00:00.000Z"
         },
         "created_at": "2020-01-01T00:00:00Z",
         "updated_at": "2020-01-01T00:00:00Z"
         }
      },
      "lab_test": {
         "name": "Lipids Panel",
         "description": "Cholesterol test",
         "method": "testkit"
      },
      "sample_id": "123456789",
      "notes": "This is a note",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z",
      "status": "collecting_sample",
      "events": [
         {
         "id": 1,
         "created_at": "2022-01-01T00:00:00Z",
         "status": "received.testkit.ordered"
         },
         {
         "id": 2,
         "created_at": "2022-01-02T00:00:00Z",
         "status": "received.testkit.requisition_created"
         },
         {
         "id": 3,
         "created_at": "2022-01-03T00:00:00Z",
         "status": "collecting_sample.testkit.transit_customer"
         }
      ]
   },
   "status": "string",
   "message": "string"
}
Patient name fields (first_name, last_name) must follow specific validation rules due to lab restrictions. See Patient Name Validation for complete details.
from vital.client import Vital
from vital.environment import VitalEnvironment
from vital.types.gender import Gender
from vital.types.patient_address_compatible import PatientAddressCompatible
from vital.types.patient_details import PatientDetails
from datetime import datetime

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

data = client.lab_tests.create_order(
    user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
    lab_test_id="5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
    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"
    ),
)

{
   "order": {
      "id": "ea7eae96-2c25-404f-b043-bfc08584610d",
      "team_id": "c26a9cc7-cdff-4f23-a5f6-74d40088c16a",
      "user_id": "63661a2b-2bb3-4125-bb1a-b590f64f057f",
      "patient_details": {
         "dob": "2020-01-01",
         "gender": "male"
      },
      "patient_address": {
         "receiver_name": "John Doe",
         "first_line": "123 Main St.",
         "second_line": "Apt. 208",
         "city": "San Francisco",
         "state": "CA",
         "zip": "91189",
         "country": "United States",
         "phone_number": "+1123456789"
      },
      "priority": false,
      "health_insurance_id": "33ec11aa-d8bf-4f46-950d-c9171be3c22f",
      "details": {
         "type": "testkit",
         "data": {
         "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
         "shipment": {
            "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
            "outbound_tracking_number": "<outbound_tracking_number>",
            "outbound_tracking_url": "<outbound_tracking_url>",
            "inbound_tracking_number": "<inbound_tracking_number>",
            "inbound_tracking_url": "<inbound_tracking_url>",
            "outbound_courier": "usps",
            "inbound_courier": "usps",
            "notes": "<notes>",
            "created_at": "2020-01-01T00:00:00.000Z",
            "updated_at": "2020-01-01T00:00:00.000Z"
         },
         "created_at": "2020-01-01T00:00:00Z",
         "updated_at": "2020-01-01T00:00:00Z"
         }
      },
      "lab_test": {
         "name": "Lipids Panel",
         "description": "Cholesterol test",
         "method": "testkit"
      },
      "sample_id": "123456789",
      "notes": "This is a note",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z",
      "status": "collecting_sample",
      "events": [
         {
         "id": 1,
         "created_at": "2022-01-01T00:00:00Z",
         "status": "received.testkit.ordered"
         },
         {
         "id": 2,
         "created_at": "2022-01-02T00:00:00Z",
         "status": "received.testkit.requisition_created"
         },
         {
         "id": 3,
         "created_at": "2022-01-03T00:00:00Z",
         "status": "collecting_sample.testkit.transit_customer"
         }
      ]
   },
   "status": "string",
   "message": "string"
}

Authorizations

​
x-vital-api-key
string
header
required

Vital Team API Key

Headers

​
X-Idempotency-Key
string | null
​
X-Idempotency-Error
string | null
Allowed value: "no-cache"

Body

application/json

Schema for the create Order endpoint.

​
user_id
string<uuid>
required
​
patient_details
object
required

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

​
patient_address
object
required
​
lab_test_id
string<uuid> | null
deprecated
​
order_set
object | null
​
collection_method
enum<string> | null

The method used to perform a lab test. ℹ️ This enum is non-exhaustive.

Available options:
testkit,
walk_in_test,
at_home_phlebotomy,
on_site_collection
​
physician
object | null
​
health_insurance
object | null
deprecated
​
priority
boolean
default:false

Defines whether order is priority or not. For some labs, this refers to a STAT order.

​
billing_type
enum<string>

ℹ️ This enum is non-exhaustive.

Available options:
client_bill,
commercial_insurance,
patient_bill_passthrough,
patient_bill
​
icd_codes
string[] | null
​
consents
Consent · object[]
​
activate_by
string<date> | null

Schedule an Order to be processed in a future date.

​
aoe_answers
AoEAnswer · object[] | null
​
passthrough
string | null
​
lab_account_id
string<uuid> | null
​
creator_member_id
string<uuid> | null

Response

Successful Response

​
order
object
required
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": "4dcf357b-536d-49fb-bdaf-f3363c2ada0f",
  "id": "42614ba6-259e-44ba-80f5-5b8a37c07860",
  "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": "44f9ab95-0ba4-4d87-9f11-2aa976fe5f1c",
  "updated_at": "2020-01-01T00:00:00Z",
  "user_id": "986787aa-f2dd-46ef-bd7b-a5854a2ccb75"
}
​
status
string
required
​
message
string
required