Orders
Register Testkit Order
- Home
- Wearables
- Lab Testing
- API Reference
- Event Catalog
- Changelog
- Users
- Debugging
- Orders
- Area Info
- At-home Phlebotomy
- Tests
- Results
- Health Insurance
- Sleep
- Meal
- Workouts
- Profile
- Activity
- Body
- Menstrual Cycle
- Vitals
- Body
- Activity
- Wellness
- Nutrition
- Team
- Member
- Invite
- Org
- Team API Keys
- Team Custom Credentials
- Team Data Pull Preferences
- Team ETL Pipeline
- Team Scope Requirements
Core
Lab Testing
Summary Data
Timeseries Data
Org Management
Orders
Register Testkit Order
POST
/
v3
/
order
/
testkit
/
register
x-vital-api-key
string
*
x-vital-api-key
Required
string
Vital Team API Key
RegisterTestkitRequest · object
*
user_id
User Id · string
*
user_id
Required
string
sample_id
Sample Id · string
*
sample_id
Required
string
patient_details
PatientDetails · object
*
patient_details
Required
object
first_name
First Name · string
*
first_name
Required
string
last_name
Last Name · string
*
last_name
Required
string
dob
Dob · string
*
dob
Required
string
gender
Gender · enum<string>
*
gender
Required
enum<string>
phone_number
Phone Number · string
*
phone_number
Required
string
email
Email · string
*
email
Required
string
patient_address
PatientAddressCompatible · object
*
patient_address
Required
object
receiver_name
Receiver Name · string
receiver_name
string
first_line
First Line · string
*
first_line
Required
string
second_line
string
second_line
string
city
City · string
*
city
Required
string
state
State · string
*
state
Required
string
zip
Zip · string
*
zip
Required
string
country
Country · string
*
country
Required
string
phone_number
string
phone_number
string
physician
object
physician
object
first_name
First Name · string
*
first_name
Required
string
last_name
Last Name · string
*
last_name
Required
string
email
string
email
string
npi
Npi · string
*
npi
Required
string
licensed_states
Licensed States · array
licensed_states
array
health_insurance
object
health_insurance
object
front_image
Option 1 · object
front_image
object
An image of the front of the patient insurance card.
content
Content · string
*
content
Required
string
content_type
Content Type · enum<string>
*
content_type
Required
enum<string>
back_image
Option 1 · object
back_image
object
An image of the back of the patient insurance card.
content
Content · string
*
content
Required
string
content_type
Content Type · enum<string>
*
content_type
Required
enum<string>
patient_signature_image
Option 1 · object
patient_signature_image
object
An image of the patient signature for health insurance billing.
content
Content · string
*
content
Required
string
content_type
Content Type · enum<string>
*
content_type
Required
enum<string>
subjective
string
subjective
string
Textual description of what are the patient symptoms and attempted treatments.
assessment_plan
string
assessment_plan
string
Textual description of what are the physician assessments and testing plans.
payor_code
string
payor_code
string
Unique identifier representing a specific Health Insurance.
insurance_id
string
insurance_id
string
Insurance unique number assigned to a patient, usually present on the insurance card.
responsible_relationship
enum<string>
responsible_relationship
enum<string>
Relationship between the patient and the insurance contractor. Values can be (Self, Spouse, Other Relationship).
responsible_details
object
responsible_details
object
Responsible details when the value of responsible_relationship is not 'Self'.
first_name
First Name · string
*
first_name
Required
string
last_name
Last Name · string
*
last_name
Required
string
address
Address · object
*
address
Required
object
first_line
First Line · string
*
first_line
Required
string
second_line
string
second_line
string
country
Country · string
*
country
Required
string
zip
Zip · string
*
zip
Required
string
city
City · string
*
city
Required
string
state
State · string
*
state
Required
string
phone_number
Phone Number · string
*
phone_number
Required
string
phone_type
Phone Type · string
phone_type
string
diagnosis_codes
array
diagnosis_codes
array
Diagnosis codes for insurance billing.
consents
Consents · array
consents
array
Authorizations
x-vital-api-key
string
headerrequiredVital Team API Key
Body
application/json
user_id
string
requiredsample_id
string
requiredpatient_details
object
requiredpatient_details.first_name
string
requiredpatient_details.last_name
string
requiredpatient_details.dob
string
requiredpatient_details.gender
enum<string>
requiredAvailable options:
female, male, other, unknown patient_details.phone_number
string
requiredpatient_details.email
string
requiredpatient_address
object
requiredpatient_address.receiver_name
string
default: patient_address.first_line
string
requiredpatient_address.second_line
string | null
patient_address.city
string
requiredpatient_address.state
string
requiredpatient_address.zip
string
requiredpatient_address.country
string
requiredpatient_address.phone_number
string | null
physician
object | null
physician.first_name
string
requiredphysician.last_name
string
requiredphysician.email
string | null
physician.npi
string
requiredphysician.licensed_states
string[]
health_insurance
object | null
health_insurance.front_image
object | null
An image of the front of the patient insurance card.
health_insurance.front_image.content
string
requiredhealth_insurance.front_image.content_type
enum<string>
requiredAvailable options:
image/jpeg health_insurance.back_image
object | null
An image of the back of the patient insurance card.
health_insurance.back_image.content
string
requiredhealth_insurance.back_image.content_type
enum<string>
requiredAvailable options:
image/jpeg health_insurance.patient_signature_image
object | null
An image of the patient signature for health insurance billing.
health_insurance.patient_signature_image.content
string
requiredhealth_insurance.patient_signature_image.content_type
enum<string>
requiredAvailable options:
image/jpeg 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 Relationship health_insurance.responsible_details
object | null
Responsible details when the value of responsible_relationship is not 'Self'.
health_insurance.responsible_details.first_name
string
requiredhealth_insurance.responsible_details.last_name
string
requiredhealth_insurance.responsible_details.address
object
requiredhealth_insurance.responsible_details.address.first_line
string
requiredhealth_insurance.responsible_details.address.second_line
string | null
health_insurance.responsible_details.address.country
string
requiredhealth_insurance.responsible_details.address.zip
string
requiredhealth_insurance.responsible_details.address.city
string
requiredhealth_insurance.responsible_details.address.state
string
requiredhealth_insurance.responsible_details.phone_number
string
requiredhealth_insurance.responsible_details.phone_type
string
default: Mobilehealth_insurance.diagnosis_codes
string[] | null
Diagnosis codes for insurance billing.
consents
object[]
consents.consentType
enum<string>
requiredAvailable options:
terms-of-use, telehealth-informed-consent, mobile-terms-and-conditions, notice-of-privacy-practices, privacy-policy, hipaa-authorization consents.version
string
default: 1.0consents.timeOfConsent
string
Response
200 - application/json
order
object
requiredorder.user_id
string
requiredUser 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
requiredThe Vital Order ID
order.team_id
string
requiredYour team id.
order.patient_details
object | null
requiredPatient Details
order.patient_details.first_name
string | null
order.patient_details.last_name
string | null
order.patient_details.dob
string
requiredorder.patient_details.gender
string
requiredorder.patient_details.phone_number
string | null
order.patient_details.email
string | null
order.patient_address
object | null
requiredPatient Address
order.patient_address.receiver_name
string
default: order.patient_address.first_line
string
requiredorder.patient_address.second_line
string | null
order.patient_address.city
string
requiredorder.patient_address.state
string
requiredorder.patient_address.zip
string
requiredorder.patient_address.country
string
requiredorder.patient_address.phone_number
string | null
order.lab_test
object
requiredThe Vital Test associated with the order
order.lab_test.id
string
requiredorder.lab_test.slug
string
requiredorder.lab_test.name
string
requiredorder.lab_test.sample_type
enum<string>
requiredAvailable options:
dried_blood_spot, serum, saliva, urine order.lab_test.method
enum<string>
requiredAvailable options:
testkit, walk_in_test, at_home_phlebotomy order.lab_test.price
number
requiredorder.lab_test.is_active
boolean
requiredDeprecated. Use status instead.
order.lab_test.status
enum<string>
requiredAvailable options:
active, pending_approval, inactive order.lab_test.fasting
boolean
default: falseDefines whether a lab test requires fasting.
order.lab_test.lab
object | null
requiredorder.lab_test.lab.id
integer
requiredorder.lab_test.lab.slug
string
requiredorder.lab_test.lab.name
string
requiredorder.lab_test.lab.first_line_address
string
requiredorder.lab_test.lab.city
string
requiredorder.lab_test.lab.zipcode
string
requiredorder.lab_test.lab.collection_methods
enum<string>[]
requiredAvailable options:
testkit, walk_in_test, at_home_phlebotomy order.lab_test.lab.sample_types
enum<string>[]
requiredAvailable options:
dried_blood_spot, serum, saliva, urine order.lab_test.markers
object[] | null
requiredorder.lab_test.markers.id
integer
requiredorder.lab_test.markers.name
string
requiredorder.lab_test.markers.slug
string
requiredorder.lab_test.markers.description
string | null
order.lab_test.markers.lab_id
integer | null
order.lab_test.markers.provider_id
string | null
order.lab_test.markers.type
enum<string> | null
Available options:
biomarker, panel order.lab_test.markers.unit
string | null
order.lab_test.markers.price
string | null
order.lab_test.markers.aoe
object | null
order.lab_test.markers.aoe.questions
object[]
requiredorder.lab_test.markers.aoe.questions.id
integer
requiredorder.lab_test.markers.aoe.questions.required
boolean
requiredorder.lab_test.markers.aoe.questions.code
string
requiredorder.lab_test.markers.aoe.questions.value
string
requiredorder.lab_test.markers.aoe.questions.type
enum<string>
requiredAvailable options:
choice, text, numeric, multi_choice order.lab_test.markers.aoe.questions.sequence
integer
requiredorder.lab_test.markers.aoe.questions.answers
object[]
requiredorder.lab_test.markers.aoe.questions.answers.id
integer
requiredorder.lab_test.markers.aoe.questions.answers.code
string
requiredorder.lab_test.markers.aoe.questions.answers.value
string
requiredorder.lab_test.markers.aoe.questions.constraint
string | null
order.lab_test.is_delegated
boolean
default: falseDenotes whether a lab test requires using non-Vital physician networks. If it does then it's delegated - no otherwise.
order.details
object
requiredorder.details.type
enum<string>
requiredAvailable options:
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.
order.details.data.id
string
requiredThe Vital walk-in test Order ID
order.details.data.created_at
string
requiredorder.details.data.updated_at
string
requiredorder.sample_id
string | null
requiredSample ID
order.notes
string | null
requiredNotes associated with the order
order.created_at
string
requiredWhen your order was created
order.updated_at
string
requiredWhen your order was last updated.
order.events
object[]
requiredorder.events.id
integer
requiredorder.events.created_at
string
requiredorder.events.status
enum<string>
requiredAvailable options:
received.walk_in_test.ordered, received.walk_in_test.requisition_created, completed.walk_in_test.completed, sample_with_lab.walk_in_test.partial_results, failed.walk_in_test.sample_error, cancelled.walk_in_test.cancelled, received.at_home_phlebotomy.ordered, received.at_home_phlebotomy.requisition_created, 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.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 order.status
enum<string> | null
Available options:
received, collecting_sample, sample_with_lab, completed, cancelled, failed order.physician
object | null
order.physician.first_name
string
requiredorder.physician.last_name
string
requiredorder.physician.npi
string
requiredorder.health_insurance_id
string | null
requiredVital ID of the health insurance.
order.requisition_form_url
string | null
requiredDEPRECATED. Requistion form url.
order.priority
boolean
default: falseDefines whether order is priority or not. For some labs, this refers to a STAT order.
order.shipping_details
object | null
requiredShipping Details. For unregistered testkit orders.
order.shipping_details.receiver_name
string
requiredorder.shipping_details.first_line
string
requiredorder.shipping_details.second_line
string | null
order.shipping_details.city
string
requiredorder.shipping_details.state
string
requiredorder.shipping_details.zip
string
requiredorder.shipping_details.country
string
requiredorder.shipping_details.phone_number
string
requiredorder.activate_by
string | null
Schedule an Order to be processed in a future date.
order.passthrough
string | null
status
string
requiredmessage
string
required