Orders
Get Orders
- 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
Get Orders
GET many orders with filters.
GET
/
v3
/
orders
x-vital-api-key
string
*
x-vital-api-key
Required
string
API key based authentication
start_date
Start Date · string
start_date
string
Date from in YYYY-MM-DD or ISO formatted date time. If a date is provided without a time, the time will be set to 00:00:00
end_date
End Date · string
end_date
string
Date to YYYY-MM-DD or ISO formatted date time. If a date is provided without a time, the time will be set to 23:59:59
user_id
User Id · string
user_id
string
Filter by user ID.
patient_name
Patient Name · string
patient_name
string
Filter by patient name.
order_ids
Order Ids · array
order_ids
array
Filter by order ids.
page
Page · integer
page
integer
size
Size · integer
size
integer
curl --request GET \
--url '{{BASE_URL}}/v3/orders' \
--header 'accept: application/json' \
--header 'x-vital-api-key: {YOUR_KEY}'
'
{
"orders": [
{
"id": "0ee312e2-6773-4a21-a6e1-506882cd98ed",
"team_id": "cbb64555-af07-46c1-be09-ef89308e9b60",
"user_id": "94e2d9f2-d600-4a23-9f08-536df378e2c7",
"patient_details": {
"dob": "2020-01-01",
"gender": "male"
},
"priority": false,
"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"
},
"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"
}
]
}
],
"total": 1,
"page": 1,
"size": 50
}
Authorizations
x-vital-api-key
string
headerrequiredAPI key based authentication
Query Parameters
start_date
string
Date from in YYYY-MM-DD or ISO formatted date time. If a date is provided without a time, the time will be set to 00:00:00
end_date
string
Date to YYYY-MM-DD or ISO formatted date time. If a date is provided without a time, the time will be set to 23:59:59
user_id
string
Filter by user ID.
patient_name
string
Filter by patient name.
order_ids
string[]
Filter by order ids.
page
integer
default: 1size
integer
default: 50Response
200 - application/json
orders
object[]
requiredorders.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.
orders.id
string
requiredThe Vital Order ID
orders.team_id
string
requiredYour team id.
orders.patient_details
object
Patient Details
orders.patient_details.first_name
string
orders.patient_details.last_name
string
orders.patient_details.dob
string
requiredorders.patient_details.gender
string
requiredorders.patient_details.phone_number
string
orders.patient_details.email
string
orders.patient_address
object
Patient Address
orders.patient_address.receiver_name
string
default: orders.patient_address.first_line
string
requiredorders.patient_address.second_line
string
orders.patient_address.city
string
requiredorders.patient_address.state
string
requiredorders.patient_address.zip
string
requiredorders.patient_address.country
string
requiredorders.patient_address.phone_number
string
orders.lab_test
object
requiredThe Vital Test associated with the order
orders.lab_test.id
string
requiredorders.lab_test.slug
string
requiredorders.lab_test.name
string
requiredorders.lab_test.sample_type
enum<string>
requiredThe type of sample used to perform a lab test.
Available options:
dried_blood_spot, serum, saliva, urine orders.lab_test.method
enum<string>
requiredThe method used to perform a lab test.
Available options:
testkit, walk_in_test, at_home_phlebotomy orders.lab_test.price
number
requiredorders.lab_test.is_active
boolean
requiredDeprecated. Use status instead.
orders.lab_test.status
enum<string>
requiredAn enumeration.
Available options:
active, pending_approval, inactive orders.lab_test.fasting
boolean
default: falseDefines whether a lab test requires fasting.
orders.lab_test.lab
object
orders.lab_test.lab.id
integer
requiredorders.lab_test.lab.slug
string
requiredorders.lab_test.lab.name
string
requiredorders.lab_test.lab.first_line_address
string
requiredorders.lab_test.lab.city
string
requiredorders.lab_test.lab.zipcode
string
requiredorders.lab_test.lab.collection_methods
enum<string>[]
requiredAvailable options:
testkit, walk_in_test, at_home_phlebotomy orders.lab_test.lab.sample_types
enum<string>[]
requiredAvailable options:
dried_blood_spot, serum, saliva, urine orders.lab_test.markers
object[]
orders.lab_test.markers.id
integer
requiredorders.lab_test.markers.name
string
requiredorders.lab_test.markers.slug
string
requiredorders.lab_test.markers.description
string
orders.lab_test.markers.lab_id
integer
orders.lab_test.markers.provider_id
string
orders.lab_test.markers.type
enum<string>
An enumeration.
Available options:
biomarker, panel orders.lab_test.markers.unit
string
orders.lab_test.markers.price
string
orders.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.
orders.details
object
requiredorders.details.type
enum<string>
requiredAvailable options:
walk_in_test orders.details.data
object
Schema for a walk-in test order in the client facing API.
To be used as part of a ClientFacingOrder.
orders.details.data.id
string
requiredThe Vital walk-in test Order ID
orders.details.data.created_at
string
requiredorders.details.data.updated_at
string
requiredorders.sample_id
string
Sample ID
orders.notes
string
Notes associated with the order
orders.created_at
string
requiredWhen your order was created
orders.updated_at
string
requiredWhen your order was last updated.
orders.events
object[]
requiredorders.events.id
integer
requiredorders.events.created_at
string
requiredorders.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 orders.status
enum<string>
An enumeration.
Available options:
received, collecting_sample, sample_with_lab, completed, cancelled, failed orders.physician
object
orders.physician.first_name
string
requiredorders.physician.last_name
string
requiredorders.physician.npi
string
requiredorders.health_insurance_id
string
Vital ID of the health insurance.
orders.requisition_form_url
string
DEPRECATED. Requistion form url.
orders.priority
boolean
default: falseDefines whether order is priority or not. For some labs, this refers to a STAT order.
orders.shipping_details
object
Shipping Details. For unregistered testkit orders.
orders.shipping_details.receiver_name
string
requiredorders.shipping_details.first_line
string
requiredorders.shipping_details.second_line
string
orders.shipping_details.city
string
requiredorders.shipping_details.state
string
requiredorders.shipping_details.zip
string
requiredorders.shipping_details.country
string
requiredorders.shipping_details.phone_number
string
requiredorders.activate_by
string
Schedule an Order to be processed in a future date.
total
integer
page
integer
size
integer
curl --request GET \
--url '{{BASE_URL}}/v3/orders' \
--header 'accept: application/json' \
--header 'x-vital-api-key: {YOUR_KEY}'
'
{
"orders": [
{
"id": "0ee312e2-6773-4a21-a6e1-506882cd98ed",
"team_id": "cbb64555-af07-46c1-be09-ef89308e9b60",
"user_id": "94e2d9f2-d600-4a23-9f08-536df378e2c7",
"patient_details": {
"dob": "2020-01-01",
"gender": "male"
},
"priority": false,
"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"
},
"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"
}
]
}
],
"total": 1,
"page": 1,
"size": 50
}