Orders
Register Testkit Order
- Home
- Wearables
- Lab Testing
- API Reference
- Event Catalog
- Changelog
Users
Debugging
Orders
At-home Phlebotomy
Tests
Results
Health Insurance
Sleep
Meal
Workouts
Profile
Activity
Body
Vitals
Body
Activity
Wellness
Nutrition
Team
Member
Invite
Org
Team API Keys
Team Custom Credentials
Team ETL Pipeline
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
API key based authentication
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>
An enumeration.
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
Street · string
*
first_line
Required
string
second_line
Street Number · 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
Phone Number · string
phone_number
string
physician
PhysicianCreateRequestBase · object
physician
object
first_name
First Name · string
*
first_name
Required
string
last_name
Last Name · string
*
last_name
Required
string
email
Email · string
email
string
npi
Npi · string
*
npi
Required
string
licensed_states
Licensed States · array
licensed_states
array
health_insurance
HealthInsuranceCreateRequest · 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
Subjective · string
subjective
string
Textual description of what are the patient symptoms and attempted treatments.
assessment_plan
Assessment Plan · string
assessment_plan
string
Textual description of what are the physician assessments and testing plans.
payor_code
Payor Code · string
payor_code
string
Unique identifier representing a specific Health Insurance.
insurance_id
Insurance Id · string
insurance_id
string
Insurance unique number assigned to a patient, usually present on the insurance card.
responsible_relationship
ResponsibleRelationship · enum<string>
responsible_relationship
enum<string>
Relationship between the patient and the insurance contractor. Values can be (Self, Spouse, Other Relationship).
responsible_details
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
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
Diagnosis Codes · array
diagnosis_codes
array
Diagnosis codes for insurance billing.
consents
Consents · array
consents
array
from datetime import datetime
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
client = Vital(
api_key="YOUR_API_KEY",
environment=VitalEnvironment.SANDBOX
)
patient_details = PatientDetails(
first_name="John",
last_name="Doe",
dob=datetime.fromisoformat("1990-01-01"),
gender=Gender.MALE,
email="email@email.com",
phone_number="123-456-7890",
)
patient_address = PatientAddressCompatible(
receiver_name="John Doe",
first_line="Main St",
second_line="123",
city="San Francisco",
state="CA",
zip="94111",
country="US",
phone_number=""
)
data = client.testkit.register(user_id="<user_id>", sample_id="<sample_id>", patient_details=patient_details, patient_address=patient_address)
{
"order": {
"id": "96edc6ef-3b2c-412b-b9e5-96f361f93aec",
"team_id": "b080b20c-e162-4cf1-9c7d-8faee72ee08e",
"user_id": "9f1e094e-1641-466b-b668-d4d3300e569f",
"patient_details": {
"first_name": "John",
"last_name": "Doe",
"phone_number": "+11234567890",
"email": "doe@email.com"
"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": "+11234567890"
},
"shipping_details": {
"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": "+11234567890"
},
"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",
"health_insurace_id": "7695cc28-f9e5-400d-95d2-ec7d9ec580df",
"notes": "This is a note",
"created_at": "2020-01-01T00:00:00Z",
"updated_at": "2020-01-01T00:00:00Z",
"status": "received",
"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.awaiting_registration"
},
{
"id": 3,
"created_at": "2022-01-02T00:00:00Z",
"status": "received.testkit.requisition_created"
},
{
"id": 4,
"created_at": "2022-01-03T00:00:00Z",
"status": "received.testkit.testkit_registered"
}
]
},
"status": "string",
"message": "string"
}
Authorizations
x-vital-api-key
string
headerrequiredAPI key based authentication
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>
requiredAn enumeration.
Available 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
patient_address.city
string
requiredpatient_address.state
string
requiredpatient_address.zip
string
requiredpatient_address.country
string
requiredpatient_address.phone_number
string
physician
object
physician.first_name
string
requiredphysician.last_name
string
requiredphysician.email
string
physician.npi
string
requiredphysician.licensed_states
string[]
health_insurance
object
health_insurance.front_image
object
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
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
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
Textual description of what are the patient symptoms and attempted treatments.
health_insurance.assessment_plan
string
Textual description of what are the physician assessments and testing plans.
health_insurance.payor_code
string
Unique identifier representing a specific Health Insurance.
health_insurance.insurance_id
string
Insurance unique number assigned to a patient, usually present on the insurance card.
health_insurance.responsible_relationship
enum<string>
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
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
default: 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[]
Diagnosis codes for insurance billing.
consents
object[]
consents.consentType
enum<string>
requiredAn enumeration.
Available 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
Patient Details
order.patient_details.first_name
string
order.patient_details.last_name
string
order.patient_details.dob
string
requiredorder.patient_details.gender
string
requiredorder.patient_details.phone_number
string
order.patient_details.email
string
order.patient_address
object
Patient Address
order.patient_address.receiver_name
string
default: order.patient_address.first_line
string
requiredorder.patient_address.second_line
string
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
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>
requiredThe type of sample used to perform a lab test.
Available options:
dried_blood_spot, serum, saliva, urine order.lab_test.method
enum<string>
requiredThe method used to perform a lab test.
Available 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>
requiredAn enumeration.
Available options:
active, pending_approval, inactive order.lab_test.fasting
boolean
default: falseDefines whether a lab test requires fasting.
order.lab_test.lab
object
order.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[]
order.lab_test.markers.id
integer
requiredorder.lab_test.markers.name
string
requiredorder.lab_test.markers.slug
string
requiredorder.lab_test.markers.description
string
order.lab_test.markers.lab_id
integer
order.lab_test.markers.provider_id
string
order.lab_test.markers.type
enum<string>
An enumeration.
Available options:
biomarker, panel order.lab_test.markers.unit
string
order.lab_test.markers.price
string
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
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
Sample ID
order.notes
string
Notes 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>
requiredAn enumeration.
Available 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>
An enumeration.
Available options:
received, collecting_sample, sample_with_lab, completed, cancelled, failed order.physician
object
order.physician.first_name
string
requiredorder.physician.last_name
string
requiredorder.physician.npi
string
requiredorder.health_insurance_id
string
Vital ID of the health insurance.
order.requisition_form_url
string
DEPRECATED. 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
Shipping Details. For unregistered testkit orders.
order.shipping_details.receiver_name
string
requiredorder.shipping_details.first_line
string
requiredorder.shipping_details.second_line
string
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
Schedule an Order to be processed in a future date.
status
string
requiredmessage
string
requiredfrom datetime import datetime
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
client = Vital(
api_key="YOUR_API_KEY",
environment=VitalEnvironment.SANDBOX
)
patient_details = PatientDetails(
first_name="John",
last_name="Doe",
dob=datetime.fromisoformat("1990-01-01"),
gender=Gender.MALE,
email="email@email.com",
phone_number="123-456-7890",
)
patient_address = PatientAddressCompatible(
receiver_name="John Doe",
first_line="Main St",
second_line="123",
city="San Francisco",
state="CA",
zip="94111",
country="US",
phone_number=""
)
data = client.testkit.register(user_id="<user_id>", sample_id="<sample_id>", patient_details=patient_details, patient_address=patient_address)
{
"order": {
"id": "96edc6ef-3b2c-412b-b9e5-96f361f93aec",
"team_id": "b080b20c-e162-4cf1-9c7d-8faee72ee08e",
"user_id": "9f1e094e-1641-466b-b668-d4d3300e569f",
"patient_details": {
"first_name": "John",
"last_name": "Doe",
"phone_number": "+11234567890",
"email": "doe@email.com"
"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": "+11234567890"
},
"shipping_details": {
"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": "+11234567890"
},
"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",
"health_insurace_id": "7695cc28-f9e5-400d-95d2-ec7d9ec580df",
"notes": "This is a note",
"created_at": "2020-01-01T00:00:00Z",
"updated_at": "2020-01-01T00:00:00Z",
"status": "received",
"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.awaiting_registration"
},
{
"id": 3,
"created_at": "2022-01-02T00:00:00Z",
"status": "received.testkit.requisition_created"
},
{
"id": 4,
"created_at": "2022-01-03T00:00:00Z",
"status": "received.testkit.testkit_registered"
}
]
},
"status": "string",
"message": "string"
}