Skip to main content
POST
/
v3
/
order
/
testkit
/
register
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"
}
Patient name fields (first_name, last_name) must follow specific validation rules due to lab restrictions. See Patient Name Validation for complete details.
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
header
required

Vital Team API Key

Body

application/json
sample_id
string
required
patient_details
object
required

Patient details with validation for first_name, last_name, email, and dob.

patient_address
object
required
user_id
string<uuid> | null
deprecated

The user ID of the patient.

physician
object | null
health_insurance
object | null
consents
Consent · object[]

Response

Successful Response

order
object
required
Example:
{
"activate_by": "2020-01-01",
"created_at": "2020-01-01T00:00:00Z",
"details": {
"data": {
"created_at": "2020-01-01T00:00:00Z",
"id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
"shipment": {
"created_at": "2020-01-01T00:00:00.000Z",
"id": "d55210cc-3d9f-4115-8262-5013f700c7be",
"inbound_courier": "usps",
"inbound_tracking_number": "<inbound_tracking_number>",
"inbound_tracking_url": "<inbound_tracking_url>",
"notes": "<notes>",
"outbound_courier": "usps",
"outbound_tracking_number": "<outbound_tracking_number>",
"outbound_tracking_url": "<outbound_tracking_url>",
"updated_at": "2020-01-01T00:00:00.000Z"
},
"updated_at": "2020-01-01T00:00:00Z"
},
"type": "testkit"
},
"events": [
{
"created_at": "2022-01-01T00:00:00Z",
"id": 1,
"status": "received.testkit.ordered"
},
{
"created_at": "2022-01-02T00:00:00Z",
"id": 2,
"status": "received.testkit.requisition_created"
},
{
"created_at": "2022-01-03T00:00:00Z",
"id": 3,
"status": "collecting_sample.testkit.transit_customer"
}
],
"has_abn": false,
"health_insurace_id": "b225e01d-013e-4508-a25a-89f252a83dad",
"id": "0d7fa813-4c37-4b11-a825-1629ab281463",
"lab_test": {
"description": "Cholesterol test",
"method": "testkit",
"name": "Lipids Panel"
},
"notes": "This is a note",
"patient_address": {
"city": "San Francisco",
"country": "United States",
"first_line": "123 Main St.",
"phone_number": "+11234567890",
"receiver_name": "John Doe",
"second_line": "Apt. 208",
"state": "CA",
"zip": "91189"
},
"patient_details": { "dob": "2020-01-01", "gender": "male" },
"requisition_form_url": "https://www.example.com",
"sample_id": "123456789",
"status": "collecting_sample",
"team_id": "058fa8d3-055d-4861-a23b-93536a729e5e",
"updated_at": "2020-01-01T00:00:00Z",
"user_id": "d93e29ae-0256-48e0-b520-f2d1fd8312c1"
}
status
string
required
message
string
required
I