Katixo/API DocumentationBeta

Laboratory

The Laboratory module manages the full diagnostic workflow — from maintaining a test catalog and placing lab orders to recording sample collection, entering results with parameter-level detail, and pathologist verification. Orders can originate from OPD consultations or IPD admissions.

Base URL: https://hospital.katixo.com/api/v1

Endpoints

GET/api/v1/lab/tests

POST/api/v1/lab/orders

GET/api/v1/lab/orders

GET/api/v1/lab/orders/{orderId}

PUT/api/v1/lab/orders/{orderId}/collect-sample

PUT/api/v1/lab/orders/{orderId}/results

PUT/api/v1/lab/orders/{orderId}/verify

Authentication

All requests require a JWT Bearer token in the Authorization header. The token must include valid tenantId, groupId, and branchId claims scoping the request to the correct hospital branch.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Enums

TestCategory

HEMATOLOGYBIOCHEMISTRYMICROBIOLOGYRADIOLOGYPATHOLOGY

SampleType

BLOODURINESTOOLSWABTISSUE

Priority

ROUTINEURGENTSTAT

OrderStatus

ORDEREDSAMPLE_COLLECTEDPROCESSINGCOMPLETEDCANCELLED

The LabOrderResponse object

{
  "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "orderNumber": "LAB-2026-00123",
  "patientId": "f6b9c4d2-8e3a-5f0b-b2c4-d6e8f0a1b3c5",
  "patientName": "Rajesh Kumar Sharma",
  "patientUhid": "UHID-2026-004571",
  "orderedBy": "Dr. Priya Mehta",
  "orderDate": "2026-06-12T09:30:00Z",
  "priority": "ROUTINE",
  "status": "COMPLETED",
  "tests": [
    {
      "testId": "b2c3d4e5-6789-abcd-ef01-23456789abcd",
      "testCode": "CBC",
      "testName": "Complete Blood Count",
      "category": "HEMATOLOGY",
      "sampleType": "BLOOD",
      "status": "COMPLETED",
      "sampleId": "SMP-20260612-0047",
      "collectedBy": "Nurse Anjali Desai",
      "collectionTime": "2026-06-12T10:15:00Z",
      "results": [
        {
          "parameterName": "Hemoglobin",
          "value": "14.2",
          "unit": "g/dL",
          "normalRange": "13.0-17.0",
          "isAbnormal": false
        },
        {
          "parameterName": "WBC Count",
          "value": "7500",
          "unit": "cells/cumm",
          "normalRange": "4000-11000",
          "isAbnormal": false
        },
        {
          "parameterName": "RBC Count",
          "value": "5.1",
          "unit": "million/cumm",
          "normalRange": "4.5-5.5",
          "isAbnormal": false
        },
        {
          "parameterName": "Platelet Count",
          "value": "2.8",
          "unit": "lakh/cumm",
          "normalRange": "1.5-4.0",
          "isAbnormal": false
        },
        {
          "parameterName": "PCV (Hematocrit)",
          "value": "42.5",
          "unit": "%",
          "normalRange": "40-50",
          "isAbnormal": false
        },
        {
          "parameterName": "MCV",
          "value": "83.3",
          "unit": "fL",
          "normalRange": "80-100",
          "isAbnormal": false
        }
      ],
      "verifiedBy": "Dr. Sunil Patil",
      "verifiedAt": "2026-06-12T14:45:00Z",
      "remarks": "All parameters within normal limits."
    }
  ]
}

Key fields

Field	Type	Description
`id`	UUID	Unique identifier for the lab order.
`orderNumber`	string	Auto-generated order number (e.g., `LAB-2026-00123`).
`patientUhid`	string	Unique Hospital Identification number of the patient.
`orderedBy`	string	Name of the referring doctor.
`priority`	Priority	`ROUTINE`, `URGENT`, or `STAT`.
`status`	OrderStatus	Current workflow status of the order.
`tests`	array	List of ordered tests with their results and verification details.
`tests[].results`	array	Parameter-level results with value, unit, normal range, and abnormal flag.

List available lab tests

GET/api/v1/lab/tests

Returns the test catalog configured for the hospital. Use query parameters to filter by category or search by test name/code.

Query parameters

Parameter	Type	Description
`category`	TestCategory	Filter by category: `HEMATOLOGY`, `BIOCHEMISTRY`, `MICROBIOLOGY`, `RADIOLOGY`, or `PATHOLOGY`.
`search`	string	Search by test name or test code.
`page`	integer	Page number (zero-based). Default: 0.
`size`	integer	Page size. Default: 20.

curl "https://hospital.katixo.com/api/v1/lab/tests?category=HEMATOLOGY&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response

{
  "success": true,
  "message": "Lab tests retrieved successfully",
  "data": {
    "content": [
      {
        "testId": "b2c3d4e5-6789-abcd-ef01-23456789abcd",
        "testCode": "CBC",
        "testName": "Complete Blood Count",
        "category": "HEMATOLOGY",
        "sampleType": "BLOOD",
        "price": 450.00,
        "turnaroundHours": 4
      },
      {
        "testId": "c3d4e5f6-789a-bcde-f012-3456789abcde",
        "testCode": "ESR",
        "testName": "Erythrocyte Sedimentation Rate",
        "category": "HEMATOLOGY",
        "sampleType": "BLOOD",
        "price": 200.00,
        "turnaroundHours": 2
      },
      {
        "testId": "d4e5f6a7-89ab-cdef-0123-456789abcdef",
        "testCode": "PT-INR",
        "testName": "Prothrombin Time with INR",
        "category": "HEMATOLOGY",
        "sampleType": "BLOOD",
        "price": 550.00,
        "turnaroundHours": 6
      }
    ],
    "page": 0,
    "size": 10,
    "totalElements": 18,
    "totalPages": 2,
    "last": false
  },
  "errors": null
}

Create a lab order

POST/api/v1/lab/orders

Creates a new lab test order for a patient. The order can be linked to an OPD appointment (appointmentId) or an IPD admission (admissionId) to track the source. The orderNumber is auto-generated by the system.

Request body

Field	Type	Required	Description
`patientId`	UUID	Yes	Patient for whom the tests are ordered.
`appointmentId`	UUID	No*	OPD appointment that originated the order.
`admissionId`	UUID	No*	IPD admission that originated the order.
`tests`	UUID[]	Yes	Array of test IDs from the test catalog.
`priority`	Priority	Yes	`ROUTINE`, `URGENT`, or `STAT`.
`notes`	string	No	Clinical notes or special instructions for the lab technician.

* Provide either appointmentId or admissionId to link the order to its source.

curl -X POST https://hospital.katixo.com/api/v1/lab/orders \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "f6b9c4d2-8e3a-5f0b-b2c4-d6e8f0a1b3c5",
    "appointmentId": "e5a8b3c1-7d2f-4e9a-a1b3-c5d7e9f0a2b4",
    "tests": [
      "b2c3d4e5-6789-abcd-ef01-23456789abcd",
      "c3d4e5f6-789a-bcde-f012-3456789abcde"
    ],
    "priority": "ROUTINE",
    "notes": "Patient is on anticoagulant therapy. Please note in CBC."
  }'

Response

{
  "success": true,
  "message": "Lab order created successfully",
  "data": {
    "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    "orderNumber": "LAB-2026-00123",
    "patientId": "f6b9c4d2-8e3a-5f0b-b2c4-d6e8f0a1b3c5",
    "patientName": "Rajesh Kumar Sharma",
    "patientUhid": "UHID-2026-004571",
    "orderedBy": "Dr. Priya Mehta",
    "orderDate": "2026-06-12T09:30:00Z",
    "priority": "ROUTINE",
    "status": "ORDERED",
    "tests": [
      {
        "testId": "b2c3d4e5-6789-abcd-ef01-23456789abcd",
        "testCode": "CBC",
        "testName": "Complete Blood Count",
        "category": "HEMATOLOGY",
        "sampleType": "BLOOD",
        "status": "ORDERED",
        "results": null,
        "verifiedBy": null,
        "verifiedAt": null
      },
      {
        "testId": "c3d4e5f6-789a-bcde-f012-3456789abcde",
        "testCode": "ESR",
        "testName": "Erythrocyte Sedimentation Rate",
        "category": "HEMATOLOGY",
        "sampleType": "BLOOD",
        "status": "ORDERED",
        "results": null,
        "verifiedBy": null,
        "verifiedAt": null
      }
    ]
  },
  "errors": null
}

List lab orders

GET/api/v1/lab/orders

Returns a paginated list of lab orders for the hospital branch. Filter by status, patient, or date to narrow results.

Query parameters

Parameter	Type	Description
`status`	OrderStatus	Filter by order status.
`patientId`	UUID	Filter orders for a specific patient.
`date`	date	Filter by order date (ISO format, e.g., `2026-06-12`).
`page`	integer	Page number (zero-based). Default: 0.
`size`	integer	Page size. Default: 20.

curl "https://hospital.katixo.com/api/v1/lab/orders?status=ORDERED&date=2026-06-12&page=0&size=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response

{
  "success": true,
  "message": "Lab orders retrieved successfully",
  "data": {
    "content": [
      {
        "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
        "orderNumber": "LAB-2026-00123",
        "patientName": "Rajesh Kumar Sharma",
        "patientUhid": "UHID-2026-004571",
        "orderedBy": "Dr. Priya Mehta",
        "orderDate": "2026-06-12T09:30:00Z",
        "priority": "ROUTINE",
        "status": "ORDERED",
        "testCount": 2
      }
    ],
    "page": 0,
    "size": 20,
    "totalElements": 34,
    "totalPages": 2,
    "last": false
  },
  "errors": null
}

Get order by ID

GET/api/v1/lab/orders/{orderId}

Returns the full lab order with all test details and results (if available). This is the primary endpoint for viewing a patient's lab report.

curl https://hospital.katixo.com/api/v1/lab/orders/a1b2c3d4-5678-9abc-def0-123456789abc \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Returns ApiResponse<LabOrderResponse> with the full order object including nested test results and verification details (see the LabOrderResponse object above).

Record sample collection

PUT/api/v1/lab/orders/{orderId}/collect-sample

Records sample collection details for an order. Transitions the order status from ORDERED to SAMPLE_COLLECTED. The sampleId typically corresponds to the barcode printed on the sample container.

Request body

Field	Type	Required	Description
`collectedBy`	string	Yes	Name of the phlebotomist or nurse who collected the sample.
`collectionTime`	datetime	Yes	ISO 8601 timestamp of sample collection.
`sampleId`	string	Yes	Barcode identifier on the sample container.

curl -X PUT https://hospital.katixo.com/api/v1/lab/orders/a1b2c3d4-5678-9abc-def0-123456789abc/collect-sample \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "collectedBy": "Nurse Anjali Desai",
    "collectionTime": "2026-06-12T10:15:00Z",
    "sampleId": "SMP-20260612-0047"
  }'

Response

{
  "success": true,
  "message": "Sample collection recorded successfully",
  "data": {
    "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    "orderNumber": "LAB-2026-00123",
    "status": "SAMPLE_COLLECTED",
    "sampleId": "SMP-20260612-0047",
    "collectedBy": "Nurse Anjali Desai",
    "collectionTime": "2026-06-12T10:15:00Z"
  },
  "errors": null
}

Enter test results

PUT/api/v1/lab/orders/{orderId}/results

Submits test results with parameter-level detail. Each test in the order can have multiple parameters (e.g., CBC includes Hemoglobin, WBC, RBC, Platelets, etc.). Transitions the order status to PROCESSING.

Request body

Field	Type	Required	Description
`results`	array	Yes	Array of test result objects.
`results[].testId`	UUID	Yes	The test ID within the order.
`results[].parameters`	array	Yes	Array of parameter results for the test.
`parameters[].parameterName`	string	Yes	Name of the measured parameter.
`parameters[].value`	string	Yes	Measured value (string to support both numeric and text results).
`parameters[].unit`	string	Yes	Unit of measurement (e.g., g/dL, cells/cumm, mg/dL).
`parameters[].normalRange`	string	Yes	Reference range (e.g., "13.0-17.0", "4000-11000").
`parameters[].isAbnormal`	boolean	Yes	Whether the value is outside the normal range.

Example: CBC results entry

curl -X PUT https://hospital.katixo.com/api/v1/lab/orders/a1b2c3d4-5678-9abc-def0-123456789abc/results \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "results": [
      {
        "testId": "b2c3d4e5-6789-abcd-ef01-23456789abcd",
        "parameters": [
          {
            "parameterName": "Hemoglobin",
            "value": "14.2",
            "unit": "g/dL",
            "normalRange": "13.0-17.0",
            "isAbnormal": false
          },
          {
            "parameterName": "WBC Count",
            "value": "7500",
            "unit": "cells/cumm",
            "normalRange": "4000-11000",
            "isAbnormal": false
          },
          {
            "parameterName": "RBC Count",
            "value": "5.1",
            "unit": "million/cumm",
            "normalRange": "4.5-5.5",
            "isAbnormal": false
          },
          {
            "parameterName": "Platelet Count",
            "value": "2.8",
            "unit": "lakh/cumm",
            "normalRange": "1.5-4.0",
            "isAbnormal": false
          },
          {
            "parameterName": "PCV (Hematocrit)",
            "value": "42.5",
            "unit": "%",
            "normalRange": "40-50",
            "isAbnormal": false
          },
          {
            "parameterName": "MCV",
            "value": "83.3",
            "unit": "fL",
            "normalRange": "80-100",
            "isAbnormal": false
          },
          {
            "parameterName": "MCH",
            "value": "27.8",
            "unit": "pg",
            "normalRange": "27-31",
            "isAbnormal": false
          },
          {
            "parameterName": "MCHC",
            "value": "33.4",
            "unit": "g/dL",
            "normalRange": "32-36",
            "isAbnormal": false
          }
        ]
      }
    ]
  }'

Response

{
  "success": true,
  "message": "Test results recorded successfully",
  "data": {
    "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    "orderNumber": "LAB-2026-00123",
    "status": "PROCESSING",
    "resultsEnteredAt": "2026-06-12T13:20:00Z"
  },
  "errors": null
}

Verify results

PUT/api/v1/lab/orders/{orderId}/verify

Approves and verifies the test results. This is typically done by a pathologist or senior lab technician. Transitions the order status from PROCESSING to COMPLETED. Once verified, the report becomes available for the referring doctor and the patient.

Request body

Field	Type	Required	Description
`verifiedBy`	string	Yes	Name of the pathologist or verifying authority.
`remarks`	string	No	Pathologist remarks or interpretation notes.

curl -X PUT https://hospital.katixo.com/api/v1/lab/orders/a1b2c3d4-5678-9abc-def0-123456789abc/verify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "verifiedBy": "Dr. Sunil Patil",
    "remarks": "All parameters within normal limits."
  }'

Response

{
  "success": true,
  "message": "Lab results verified successfully",
  "data": {
    "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    "orderNumber": "LAB-2026-00123",
    "status": "COMPLETED",
    "verifiedBy": "Dr. Sunil Patil",
    "verifiedAt": "2026-06-12T14:45:00Z",
    "remarks": "All parameters within normal limits."
  },
  "errors": null
}

Workflow

A lab order follows this lifecycle:

ORDERED — Doctor places the order via POST /api/v1/lab/orders. System auto-generates the order number.

SAMPLE_COLLECTED — Phlebotomist records sample collection with barcode via PUT .../collect-sample.

PROCESSING — Lab technician enters parameter-level results via PUT .../results.

COMPLETED — Pathologist verifies and approves results via PUT .../verify. Report is now final.

An order can be moved to CANCELLED at any point before verification.

Error responses

Validation errors and business rule violations are returned inside the errors array:

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    "patientId: must not be null",
    "tests: must not be empty",
    "priority: must not be null"
  ]
}

Status	Reason
`400`	Validation error (missing required fields, invalid test IDs, empty results).
`401`	Missing or invalid JWT Bearer token.
`403`	Insufficient permissions (e.g., only pathologists can verify results).
`404`	Order or patient not found for the given ID.
`409`	Invalid status transition (e.g., entering results before sample collection).