Create Order

POST

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"
}

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

Body

application/json

Schema for the create Order endpoint.

user_id

string

required

patient_details

object

required

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

patient_details.first_name

string

required

Required string length: 1 - 50

patient_details.last_name

string

required

Required string length: 1 - 50

patient_details.dob

string

required

patient_details.gender

enum<string>

required

ℹ️ This enum is non-exhaustive.

Available options:

female,

male,

other,

unknown

patient_details.phone_number

string

required

patient_details.email

string

required

patient_details.medical_proxy

object | null

Parent/medical_proxy details. Required if patient is a minor.

patient_details.race

enum<string> | null

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

patient_details.ethnicity

enum<string> | null

If not provided, will be set to 'Not Specified'

Available options:

hispanic,

non_hispanic,

ashkenazi_jewish,

other

patient_details.sexual_orientation

enum<string> | null

If not provided, will be set to 'Not Specified'

Available options:

lesbian_gay_or_homosexual,

heterosexual_or_straight,

bisexual,

dont_know,

other

patient_details.gender_identity

enum<string> | null

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

object

required

lab_test_id

string | 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

physician

object | null

health_insurance

object | null

deprecated

health_insurance.front_image

object | null

An image of the front of the patient insurance card.

health_insurance.back_image

object | null

An image of the back of the patient insurance card.

health_insurance.patient_signature_image

object | null

An image of the patient signature for health insurance billing.

health_insurance.subjective

string | null

Textual description of what are the patient symptoms and attempted treatments.

health_insurance.assessment_plan

string | null

Textual description of what are the physician assessments and testing plans.

health_insurance.payor_code

string | null

Unique identifier representing a specific Health Insurance.

health_insurance.insurance_id

string | null

Insurance unique number assigned to a patient, usually present on the insurance card.

health_insurance.responsible_relationship

enum<string> | null

Relationship between the patient and the insurance contractor. Values can be (Self, Spouse, Other Relationship).

Available options:

Self,

Spouse,

Other

health_insurance.responsible_details

object | null

Responsible details when the value of responsible_relationship is not 'Self'.

health_insurance.diagnosis_codes

string[] | null

Diagnosis codes for insurance billing.

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

object[]

activate_by

string | null

Schedule an Order to be processed in a future date.

aoe_answers

object[] | null

passthrough

string | null

Response

200

application/json

Successful Response

order

object

required

order.user_id

string

required

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.

order.id

string

required

The Vital Order ID

order.team_id

string

required

Your team id.

order.patient_details

object | null

required

Patient Details

order.patient_details.dob

string

required

order.patient_details.gender

string

required

order.patient_details.first_name

string | null

order.patient_details.last_name

string | null

order.patient_details.phone_number

string | null

order.patient_details.email

string | null

order.patient_details.medical_proxy

object | null

Parent/medical_proxy details. Required if patient is a minor.

order.patient_details.race

enum<string> | null

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

order.patient_details.ethnicity

enum<string> | null

If not provided, will be set to 'Not Specified'

Available options:

hispanic,

non_hispanic,

ashkenazi_jewish,

other

order.patient_details.sexual_orientation

enum<string> | null

If not provided, will be set to 'Not Specified'

Available options:

lesbian_gay_or_homosexual,

heterosexual_or_straight,

bisexual,

dont_know,

other

order.patient_details.gender_identity

enum<string> | null

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

order.patient_address

object | null

required

Patient Address

order.lab_test

object

required

The Vital Test associated with the order

order.lab_test.id

string

required

order.lab_test.slug

string

required

order.lab_test.name

string

required

order.lab_test.sample_type

enum<string>

required

Available options:

dried_blood_spot,

arm_collector,

serum,

saliva,

urine

order.lab_test.method

enum<string>

required

Available options:

testkit,

walk_in_test,

at_home_phlebotomy

order.lab_test.price

number

required

order.lab_test.is_active

boolean

required

Deprecated. Use status instead.

order.lab_test.status

enum<string>

required

Available options:

active,

pending_approval,

inactive

order.lab_test.lab

object | null

required

Example:

{
  "city": "San Francisco",
  "collection_methods": ["testkit"],
  "first_line_address": "123 Main St",
  "id": 1,
  "name": "LabCorp",
  "sample_types": ["saliva"],
  "slug": "labcorp",
  "zipcode": "91789"
}

order.lab_test.markers

object[] | null

required

order.lab_test.fasting

boolean

default:false

Defines whether a lab test requires fasting.

order.lab_test.is_delegated

boolean

default:false

Denotes whether a lab test requires using non-Vital physician networks. If it does then it's delegated - no otherwise.

order.lab_test.auto_generated

boolean

default:false

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"
  }
}

order.details

object

required

order.details.type

string

required

Allowed value: "walk_in_test"

order.details.data

object | null

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"
}

order.sample_id

string | null

required

Sample ID

order.notes

string | null

required

Notes associated with the order

order.created_at

string

required

When your order was created

order.updated_at

string

required

When your order was last updated.

order.events

object[]

required

order.health_insurance_id

string | null

required

Vital ID of the health insurance.

order.requisition_form_url

string | null

required

DEPRECATED. Requistion form url.

order.shipping_details

object | null

required

Shipping Details. For unregistered testkit orders.

order.has_abn

boolean

required

Defines whether the order has an Advanced Beneficiary Notice (ABN) form or not.

order.status

enum<string> | null

ℹ️ This enum is non-exhaustive.

Available options:

received,

collecting_sample,

sample_with_lab,

completed,

cancelled,

failed

order.physician

object | null

order.priority

boolean

default:false

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

order.activate_by

string | null

Schedule an Order to be processed in a future date.

order.passthrough

string | null

order.billing_type

enum<string>

ℹ️ This enum is non-exhaustive.

Available options:

client_bill,

commercial_insurance,

patient_bill_passthrough,

patient_bill

order.icd_codes

string[] | null

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"
}

status

string

required

message

string

required

Get Orders

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"
}

Orders

Area Info

At-home Phlebotomy

Patient Service Center (PSC)

Tests

Results

Health Insurance

Authorizations

Body

Response