Orders
At-home Phlebotomy
Patient Service Center (PSC)
Tests
Health Insurance
Orders
Get Orders
GET many orders with filters.
GET
/
v3
/
orders
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
}
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
Vital Team API Key
Query Parameters
Search by order id, user id, patient name, shipping dob, or shipping recipient name.
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
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
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
Date to 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
Available options:
created_at, patient_name, last_status Available options:
asc, desc Filter by user ID.
Filter by patient name.
Filter by shipping recipient name.
Filter by order ids.
Required range:
x >= 1Required range:
1 <= x <= 100Response
200
application/json
Successful Response
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.
The Vital Order ID
Your team id.
Patient Address
The Vital Test associated with the order
Available options:
dried_blood_spot, arm_collector, serum, saliva, urine Available options:
testkit, walk_in_test, at_home_phlebotomy Deprecated. Use status instead.
Available options:
active, pending_approval, inactive The method used to perform a lab test.
Available options:
testkit, walk_in_test, at_home_phlebotomy The type of sample used to perform a lab test.
Available options:
dried_blood_spot, arm_collector, serum, saliva, urine Example:
{
"city": "San Francisco",
"collection_methods": ["testkit"],
"first_line_address": "123 Main St",
"id": 1,
"name": "LabCorp",
"sample_types": ["saliva"],
"slug": "labcorp",
"zipcode": "91789"
}
Available options:
biomarker, panel Defines whether a lab test requires fasting.
Denotes whether a lab test requires using non-Vital physician networks. If it does then it's delegated - no otherwise.
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"
}
}
Available options:
walk_in_test Schema for a walk-in test order in the client facing API.
To be used as part of a ClientFacingOrder.
Example:
{
"appointment_id": "a608f30e-7a0f-4e1b-b53a-a87a549cd890",
"created_at": "2020-01-01T00:00:00Z",
"id": "688654c9-98b3-478a-ad64-bbbeb600f694",
"updated_at": "2020-01-01T00:00:00Z"
}
Sample ID
Notes associated with the order
When your order was created
When your order was last updated.
Available options:
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, 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, 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 Vital ID of the health insurance.
DEPRECATED. Requistion form url.
Shipping Details. For unregistered testkit orders.
Available options:
received, collecting_sample, sample_with_lab, completed, cancelled, failed Defines whether order is priority or not. For some labs, this refers to a STAT order.
Schedule an Order to be processed in a future date.
Available options:
client_bill, commercial_insurance, patient_bill_passthrough, patient_bill 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
}