---
title: "Create Order"
method: POST
path: "/v3/order"
tags: ["order"]
---

# Create Order

`POST /v3/order`

## Headers

- `X-Idempotency-Key` string, nullable
- `X-Idempotency-Error` 'no-cache', nullable

## Request body

- CreateOrderRequestCompatible — Schema for the create Order endpoint.
  - `user_id` string, uuid, required
  - `lab_test_id` string, uuid, nullable
  - `order_set` OrderSetRequest
    - `lab_test_ids` string[], nullable
    - `add_on` AddOnOrder
      - `marker_ids` integer[], nullable
      - `provider_ids` string[], nullable
    - `lab_account_id` string, uuid, nullable
  - `collection_method` 'testkit' | 'walk_in_test' | 'at_home_phlebotomy' | 'on_site_collection' — The method used to perform a lab test. ℹ️ This enum is non-exhaustive.
  - `physician` PhysicianCreateRequest
    - `first_name` string, required
    - `last_name` string, required
    - `email` string, nullable
    - `npi` string, required
    - `licensed_states` string[]
    - `signature_image` union — An image of the physician signature for health insurance billing
      - Jpeg
        - `content` string, binary, required
        - `content_type` 'image/jpeg', required
      - Png
        - `content` string, binary, required
        - `content_type` 'image/png', required
  - `health_insurance` HealthInsuranceCreateRequest
    - `front_image` union — An image of the front of the patient insurance card.
      - Jpeg
        - `content` string, binary, required
        - `content_type` 'image/jpeg', required
      - Png
        - `content` string, binary, required
        - `content_type` 'image/png', required
    - `back_image` union — An image of the back of the patient insurance card.
      - Jpeg
        - `content` string, binary, required
        - `content_type` 'image/jpeg', required
      - Png
        - `content` string, binary, required
        - `content_type` 'image/png', required
    - `patient_signature_image` union — An image of the patient signature for health insurance billing.
      - Jpeg
        - `content` string, binary, required
        - `content_type` 'image/jpeg', required
      - Png
        - `content` string, binary, required
        - `content_type` 'image/png', required
    - `subjective` string, nullable — Textual description of what are the patient symptoms and attempted treatments.
    - `assessment_plan` string, nullable — Textual description of what are the physician assessments and testing plans.
    - `payor_code` string, nullable — Unique identifier representing a specific Health Insurance.
    - `insurance_id` string, nullable — Insurance unique number assigned to a patient, usually present on the insurance card.
    - `responsible_relationship` 'Self' | 'Spouse' | 'Other' — ℹ️ This enum is non-exhaustive.
    - `responsible_details` VitalCoreSchemasDbSchemasLabTestHealthInsurancePersonDetails
      - `first_name` string, required
      - `last_name` string, required
      - `address` Address, required
        - `first_line` string, required
        - `second_line` string, nullable
        - `country` string, required
        - `zip` string, required
        - `city` string, required
        - `state` string, required
        - `access_notes` string, nullable
      - `phone_number` string, required
      - `phone_type` string
    - `diagnosis_codes` string[], nullable — Diagnosis codes for insurance billing.
  - `priority` boolean — Defines whether order is priority or not. For some labs, this refers to a STAT order.
  - `billing_type` 'client_bill' | 'commercial_insurance' | 'patient_bill_passthrough' | 'patient_bill' — ℹ️ This enum is non-exhaustive.
  - `icd_codes` string[], nullable
  - `consents` Consent[]
    - `consentType` 'terms-of-use' | 'telehealth-informed-consent' | 'mobile-terms-and-conditions' | 'notice-of-privacy-practices' | 'privacy-policy' | 'hipaa-authorization', required — ℹ️ This enum is non-exhaustive.
    - `version` string
    - `timeOfConsent` string, date-time
  - `activate_by` string, date, nullable — Schedule an Order to be processed in a future date.
  - `aoe_answers` AoEAnswer[], nullable
    - `marker_id` integer, required
    - `question_id` integer, required
    - `answer` string, required
  - `passthrough` string, nullable
  - `clinical_notes` string, nullable
  - `lab_account_id` string, uuid, nullable
  - `creator_member_id` string, uuid, nullable
  - `patient_details` PatientDetailsWithValidation, required — Patient details with validation for first_name, last_name, email, and dob.
    - `first_name` string, required
    - `last_name` string, required
    - `dob` string, date, required
    - `gender` 'female' | 'male' | 'other' | 'unknown', required — ℹ️ This enum is non-exhaustive.
    - `phone_number` string, required
    - `email` string, email, required
    - `medical_proxy` GuarantorDetails
      - `first_name` string, required
      - `last_name` string, required
      - `address` Address, required
        - `first_line` string, required
        - `second_line` string, nullable
        - `country` string, required
        - `zip` string, required
        - `city` string, required
        - `state` string, required
        - `access_notes` string, nullable
      - `phone_number` string, required
      - `household_income` integer, nullable
      - `household_size` integer, nullable
      - `email` string, nullable
    - `race` 'african_american_or_black' | 'asian' | 'indigenous_native_american_alaska_native' | 'other' | 'pacific_islander_or_hawaiian' | 'white_caucasian' — ℹ️ This enum is non-exhaustive.
    - `ethnicity` 'hispanic' | 'non_hispanic' | 'ashkenazi_jewish' | 'other' — ℹ️ This enum is non-exhaustive.
    - `sexual_orientation` 'lesbian_gay_or_homosexual' | 'heterosexual_or_straight' | 'bisexual' | 'dont_know' | 'other' — ℹ️ This enum is non-exhaustive.
    - `gender_identity` 'male' | 'female' | 'female_to_male_ftm_transgender_male_trans_man' | 'male_to_female_mtf_transgender_female_trans_woman' | 'genderqueer' | 'other' — ℹ️ This enum is non-exhaustive.
    - `household_income` integer, nullable — Household income in USD. If not provided, will be set to None
    - `household_size` integer, nullable — Household size. If not provided, will be set to None
  - `patient_address` PatientAddressWithValidation, required
    - `receiver_name` string
    - `first_line` string, required
    - `second_line` string, nullable
    - `city` string, required
    - `state` string, required
    - `zip` string, required
    - `country` string, required
    - `access_notes` string, nullable
    - `phone_number` string, nullable

## Response `200`

Successful Response

- PostOrderResponse
  - `order` ClientFacingOrder, required
    - `user_id` string, uuid, 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.
    - `id` string, uuid, required — The Vital Order ID
    - `team_id` string, uuid, required — Your team id.
    - `patient_details` ClientFacingPatientDetailsCompatible, required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `dob` string, date-time, required
      - `gender` string, required
      - `phone_number` string, nullable
      - `email` string, nullable
      - `medical_proxy` GuarantorDetails
        - `first_name` string, required
        - `last_name` string, required
        - `address` Address, required
          - `first_line` string, required
          - `second_line` string, nullable
          - `country` string, required
          - `zip` string, required
          - `city` string, required
          - `state` string, required
          - `access_notes` string, nullable
        - `phone_number` string, required
        - `household_income` integer, nullable
        - `household_size` integer, nullable
        - `email` string, nullable
      - `race` 'african_american_or_black' | 'asian' | 'indigenous_native_american_alaska_native' | 'other' | 'pacific_islander_or_hawaiian' | 'white_caucasian' — ℹ️ This enum is non-exhaustive.
      - `ethnicity` 'hispanic' | 'non_hispanic' | 'ashkenazi_jewish' | 'other' — ℹ️ This enum is non-exhaustive.
      - `sexual_orientation` 'lesbian_gay_or_homosexual' | 'heterosexual_or_straight' | 'bisexual' | 'dont_know' | 'other' — ℹ️ This enum is non-exhaustive.
      - `gender_identity` 'male' | 'female' | 'female_to_male_ftm_transgender_male_trans_man' | 'male_to_female_mtf_transgender_female_trans_woman' | 'genderqueer' | 'other' — ℹ️ This enum is non-exhaustive.
    - `patient_address` PatientAddressCompatible, required
      - `receiver_name` string
      - `first_line` string, required
      - `second_line` string, nullable
      - `city` string, required
      - `state` string, required
      - `zip` string, required
      - `country` string, required
      - `access_notes` string, nullable
      - `phone_number` string, nullable
    - `lab_test` ClientFacingLabTest, required
      - `id` string, uuid, required
      - `slug` string, required
      - `name` string, required
      - `sample_type` 'dried_blood_spot' | 'arm_collector' | 'serum' | 'saliva' | 'urine' | 'stool', required — The type of sample used to perform a lab test. ℹ️ This enum is non-exhaustive.
      - `method` 'testkit' | 'walk_in_test' | 'at_home_phlebotomy' | 'on_site_collection', required — The method used to perform a lab test. ℹ️ This enum is non-exhaustive.
      - `price` number, required
      - `is_active` boolean, required — Deprecated. Use status instead.
      - `status` 'active' | 'pending_approval' | 'inactive', required — ℹ️ This enum is non-exhaustive.
      - `fasting` boolean — Defines whether a lab test requires fasting.
      - `lab` ClientFacingLab, required
        - `id` integer, required
        - `slug` string, required
        - `name` string, required
        - `first_line_address` string, required
        - `city` string, required
        - `zipcode` string, required
        - `collection_methods` LabTestCollectionMethod[], required
        - `sample_types` LabTestSampleType[], required
        - `logo_url` string, nullable
      - `markers` ClientFacingMarker[], nullable, required
        - `id` integer, required
        - `name` string, required
        - `slug` string, required
        - `description` string, nullable
        - `lab_id` integer, nullable
        - `provider_id` string, nullable
        - `type` 'biomarker' | 'panel' — ℹ️ This enum is non-exhaustive.
        - `unit` string, nullable
        - `price` string, nullable
        - `aoe` AoE
          - `questions` Question[], required
            - `id` integer, required
            - `required` boolean, required
            - `code` string, required
            - `value` string, required
            - `type` 'choice' | 'text' | 'numeric' | 'multi_choice', required — ℹ️ This enum is non-exhaustive.
            - `sequence` integer, required
            - `answers` Answer[], required
              - …
            - `constraint` string, nullable
            - `default` string, nullable
        - `a_la_carte_enabled` boolean
        - `common_tat_days` integer, nullable
        - `worst_case_tat_days` integer, nullable
        - `is_orderable` boolean, nullable
      - `is_delegated` boolean — Deprecated and always false. Delegation is now at the lab account level. Used to denote whether a lab test requires using non-Vital physician networks.
      - `auto_generated` boolean — Whether the lab test was auto-generated by Vital
      - `has_collection_instructions` boolean, nullable — Whether or not the lab test has collection instructions.
      - `common_tat_days` integer, nullable — The common turnaround time in days for the lab test. This is the expected time for the lab to process the test and return results.
      - `worst_case_tat_days` integer, nullable — The worst-case turnaround time in days for the lab test. This is the maximum time the lab may take to process the test and return results.
    - `details` union, required
      - ClientFacingWalkInOrderDetails
        - `type` 'walk_in_test', required
        - `data` ClientFacingWalkInTestOrder — Schema for a walk-in test order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Vital walk-in test Order ID
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
          - `appointment_id` string, uuid, nullable
      - ClientFacingTestKitOrderDetails
        - `type` 'testkit', required
        - `data` ClientFacingTestkitOrder — Schema for a testkit order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Vital TestKit Order ID
          - `shipment` ClientFacingShipment, required — Schema for a Shipment in the client facing API. To be used as part of a ClientFacingTestkitOrder.
            - `id` string, uuid, required — The Vital Shipment ID
            - `outbound_tracking_number` string, nullable, required — Tracking number for delivery to customer
            - `outbound_tracking_url` string, nullable, required — Tracking url for delivery to customer
            - `inbound_tracking_number` string, nullable, required — Tracking number for delivery to lab
            - `inbound_tracking_url` string, nullable, required — Tracking url for delivery to lab
            - `outbound_courier` string, nullable, required — Courier used for delivery to customer
            - `inbound_courier` string, nullable, required — Courier used for delivery to lab
            - `notes` string, nullable, required — Notes associated to the Vital shipment
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
      - ClientFacingAtHomePhlebotomyOrderDetails
        - `type` 'at_home_phlebotomy', required
        - `data` ClientFacingAtHomePhlebotomyOrder — Schema for a at-home-phlebotomy test order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Vital at-home phlebotomy Order ID
          - `appointment_id` string, uuid, nullable
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
      - ClientFacingOnSiteCollectionOrderDetails
        - `type` 'on_site_collection', required
        - `data` ClientFacingOnSiteCollectionOrder — Schema for an on-site collection order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Junction on-site collection Order ID
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
    - `sample_id` string, nullable, required — Sample ID
    - `notes` string, nullable, required — Notes associated with the order
    - `clinical_notes` string, nullable
    - `created_at` string, date-time, required — When your order was created
    - `updated_at` string, date-time, required — When your order was last updated.
    - `events` ClientFacingOrderEvent[], required
      - `id` integer, required
      - `created_at` string, date-time, required
      - `status` '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' | 'collecting_sample.walk_in_test.redraw_available' | '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' | 'sample_with_lab.testkit.lab_processing_blocked' | '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' | 'received.on_site_collection.ordered' | 'received.on_site_collection.requisition_created' | 'received.on_site_collection.requisition_bypassed' | 'sample_with_lab.on_site_collection.draw_completed' | 'completed.on_site_collection.completed' | 'cancelled.on_site_collection.cancelled' | 'sample_with_lab.on_site_collection.partial_results' | 'failed.on_site_collection.sample_error' | 'completed.walk_in_test.corrected' | 'completed.at_home_phlebotomy.corrected' | 'completed.on_site_collection.corrected' | 'completed.testkit.corrected', required — ℹ️ This enum is non-exhaustive.
      - `status_detail` 'fulfillment_error' | 'date_of_collection_unspecified' | 'demographic_information_unspecified' | 'demographic_information_mismatch' | 'sample_quantity_not_sufficient' | 'sample_contaminated' | 'sample_stability_exceeded' | 'sample_hemolyzed' | 'sample_improper_collection' — A descriptive-only additional field to be used in combination with OrderStatus. Exposed in the API. ℹ️ This enum is non-exhaustive.
    - `status` 'received' | 'collecting_sample' | 'sample_with_lab' | 'completed' | 'cancelled' | 'failed' — ℹ️ This enum is non-exhaustive.
    - `last_event` ClientFacingOrderEvent, required
      - `id` integer, required
      - `created_at` string, date-time, required
      - `status` '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' | 'collecting_sample.walk_in_test.redraw_available' | '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' | 'sample_with_lab.testkit.lab_processing_blocked' | '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' | 'received.on_site_collection.ordered' | 'received.on_site_collection.requisition_created' | 'received.on_site_collection.requisition_bypassed' | 'sample_with_lab.on_site_collection.draw_completed' | 'completed.on_site_collection.completed' | 'cancelled.on_site_collection.cancelled' | 'sample_with_lab.on_site_collection.partial_results' | 'failed.on_site_collection.sample_error' | 'completed.walk_in_test.corrected' | 'completed.at_home_phlebotomy.corrected' | 'completed.on_site_collection.corrected' | 'completed.testkit.corrected', required — ℹ️ This enum is non-exhaustive.
      - `status_detail` 'fulfillment_error' | 'date_of_collection_unspecified' | 'demographic_information_unspecified' | 'demographic_information_mismatch' | 'sample_quantity_not_sufficient' | 'sample_contaminated' | 'sample_stability_exceeded' | 'sample_hemolyzed' | 'sample_improper_collection' — A descriptive-only additional field to be used in combination with OrderStatus. Exposed in the API. ℹ️ This enum is non-exhaustive.
    - `physician` ClientFacingPhysician
      - `first_name` string, required
      - `last_name` string, required
      - `npi` string, required
    - `health_insurance_id` string, uuid, nullable, required — Vital ID of the health insurance.
    - `requisition_form_url` string, nullable, required — DEPRECATED. Requistion form url.
    - `priority` boolean — Defines whether order is priority or not. For some labs, this refers to a STAT order.
    - `shipping_details` ShippingAddress, required
      - `receiver_name` string, required
      - `first_line` string, required
      - `second_line` string, nullable
      - `city` string, required
      - `state` string, required
      - `zip` string, required
      - `country` string, required
      - `phone_number` string, required
    - `activate_by` string, date, nullable — Schedule an Order to be processed in a future date.
    - `passthrough` string, nullable
    - `billing_type` 'client_bill' | 'commercial_insurance' | 'patient_bill_passthrough' | 'patient_bill' — ℹ️ This enum is non-exhaustive.
    - `icd_codes` string[], nullable
    - `has_abn` boolean, required — Defines whether the order has an Advanced Beneficiary Notice (ABN) form or not.
    - `interpretation` 'normal' | 'abnormal' | 'critical' | 'unknown' — ℹ️ This enum is non-exhaustive.
    - `has_missing_results` boolean, nullable — Defines whether the order result has missing biomarkers.
    - `expected_result_by_date` string, date, nullable — The common-case date by which the order result is expected to be available.
    - `worst_case_result_by_date` string, date, nullable — The latest date by which the order result is expected to be available.
    - `origin` 'initial' | 'redraw' | 'recreation' — ℹ️ This enum is non-exhaustive.
    - `order_transaction` ClientFacingOrderTransaction — Order transaction info.
      - `id` string, uuid, required
      - `status` 'active' | 'completed' | 'cancelled', required — ℹ️ This enum is non-exhaustive.
      - `orders` ClientFacingOrderInTransaction[], required
        - `id` string, uuid, required
        - `low_level_status` 'ordered' | 'requisition_created' | 'requisition_bypassed' | 'transit_customer' | 'out_for_delivery' | 'with_customer' | 'transit_lab' | 'delivered_to_lab' | 'completed' | 'failure_to_deliver_to_lab' | 'failure_to_deliver_to_customer' | 'problem_in_transit_lab' | 'problem_in_transit_customer' | 'sample_error' | 'appointment_scheduled' | 'appointment_cancelled' | 'appointment_pending' | 'draw_completed' | 'cancelled' | 'lost' | 'do_not_process' | 'partial_results' | 'awaiting_registration' | 'registered' | 'redraw_available' | 'corrected' | 'lab_processing_blocked' — ℹ️ This enum is non-exhaustive.
        - `low_level_status_created_at` string, date-time, nullable
        - `origin` 'initial' | 'redraw' | 'recreation' — ℹ️ This enum is non-exhaustive.
        - `parent_id` string, uuid, nullable
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
  - `status` string, required
  - `message` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/tryvital/apis/junction-api.md) · [All operations](https://skmtc.net/tryvital/apis/junction-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryvital/junction-api/versions/d28f5cec7d79/schema)