MedConnect LIS Integration Guide

API Documentation & Integration Reference — Version 2.0.0

For LIS/HIS Providers

This guide provides everything you need to integrate your Laboratory Information System (LIS) or Hospital Information System (HIS) with MedConnect.

Sham Software Consultancy — 2026

⬇ Download Postman Collection

1. Overview and Authentication

1.1 What is MedConnect?

MedConnect is an orchestration engine that connects medical laboratory instruments (analyzers) with Laboratory Information Systems (LIS/HIS) by abstracting device protocol complexity behind simple API interfaces. It handles protocol translation, test mapping, order routing, result delivery, and automatic retry — so HIS/LIS systems never need to understand ASTM, HL7, or device-specific protocols directly.

1.2 Communication Flow

The integration follows a three-phase workflow regardless of mode:

1.3 Authentication

Bearer Token Authentication

MedConnect supports optional Bearer token authentication. When configured, MedConnect includes the token in every request:

POST /api/orders HTTP/1.1
Authorization: Bearer <your-token-here>
Content-Type: application/json

Setting	Required	Description
Bearer Token	No	Static token sent in the Authorization header

If the Bearer Token field is left empty, MedConnect will not send an Authorization header.

Custom Request Headers

MedConnect sends the following headers with every request for traceability:

Header	Description
`X-Request-ID`	Unique UUID for each request (for log correlation)
`X-Request-Timestamp`	UTC timestamp of when the request was created
`X-Expected-Sample`	The sample number being queried (on order requests only)
`Content-Type`	application/json
`Accept`	application/json

1.4 Retry Behavior

MedConnect implements retry logic to handle transient failures:

Scenario	Retries	Backoff Strategy
Order retrieval	Up to 3 attempts	Linear: 100ms × attempt number
Transient HTTP errors (5xx, timeout)	Up to 2 additional retries	Exponential: 2^n seconds

Result submission and test retrieval use a single attempt. Ensure your endpoints are reliable.

2. HTTP REST API Reference

This section documents the HTTP REST API that the LIS/HIS provider must implement. MedConnect acts as the HTTP client and calls these endpoints.

All endpoints use HTTP POST with JSON payloads.

2.1 Endpoint Summary

#	Endpoint Name	Purpose	Required
1	Tests API	Retrieve available LIS tests for mapping	Yes
2	Orders API	Retrieve order details by sample number	Yes
3	Results API	Submit test results	Yes
4	Processed API	Notify LIS that an order was processed	No

2.2 Tests API

Used by MedConnect to search and retrieve the LIS test catalog. This enables test mapping between instrument test codes and LIS test codes.

Request

POST <LabTestsAPI URL>
Content-Type: application/json
Authorization: Bearer <token>

Field	Type	Required	Description
`Name`	string	No	Test name search filter (partial match)
`Code`	string	No	Test code search filter (partial match)

{"Name": "", "Code": "cbc"}

Response

Field	Type	Required	Description
`ID`	string	Yes	Unique LIS test identifier
`Name`	string	Yes	Human-readable test name
`Code`	string	Yes	LIS test code
`Type`	string	No	Sample type for this test

{"tests": [{"ID": "101", "Name": "COMPLETE BLOOD COUNT (CBC)", "Code": "CBC", "Type": "EDTA Whole Blood"}]}

2.3 Orders API

Used by MedConnect to retrieve order details for a specific sample. MedConnect sends this request when an instrument scans a barcode.

POST <TransactionInfoAPI URL>
Content-Type: application/json
X-Request-ID: <unique-uuid>
X-Expected-Sample: <sample-number>

Field	Type	Required	Description
`SampleNumber`	string	Yes	The barcode/sample number to look up
`allTests`	string	No	Send "1" to retrieve all tests. Only relevant when Processed API is also used.

{"SampleNumber": "2071720201"}

The SampleNumber in the response must match the SampleNumber in the request. If they differ, MedConnect will reject the response and retry.

2.4 Results API

Used by MedConnect to submit completed test results to the LIS.

POST <ResultAPI URL>
Content-Type: application/json

Field	Type	Required	Description
`SampleNumber`	string	Yes	Sample number the result belongs to
`TestCode`	string	Yes	LIS test code
`SubTestCode`	string	No	LIS sub-test code (used for panel components)
`Result`	string	Yes	The test result value

{"results": [{"SampleNumber": "2071630101", "TestCode": "15/11012", "SubTestCode": "", "Result": "36.19"}]}

2.5 Processed API (Optional)

Used by MedConnect to notify the LIS that an order has been accepted and processed by the instrument. This allows the LIS to track order status and prevent duplicate processing.

POST <OrderCompletedAPI URL>
Content-Type: application/json

Field	Type	Required	Description
`SampleNumber`	string	Yes	The processed order sample number
`Tests`	string	Yes	JSON-serialized array of test IDs that were processed

{"SampleNumber": "2071720201", "Tests": "[\"100\",\"102\",\"300\"]"}

2.6 Local API Server (Incoming Push)

MedConnect can optionally run a local HTTP server to receive order pushes from the LIS. This is useful for LIS systems that prefer to actively push orders rather than waiting for MedConnect to poll.

POST http://<LocalAPIAddress>:<LocalAPIPort>/api/getSampleData
Content-Type: application/json

Status	Condition
422	Order data is missing or empty
404	Unknown route
405	Wrong HTTP method (only POST is accepted)
500	Internal server error

The local API server requires administrator privileges to run and bind to the specified address/port.

2.7 Error Handling

HTTP Error Response Format

When the LIS returns an error, MedConnect expects the following JSON structure:

{"message": "Description of what went wrong", "errors": ["Detailed error 1"]}

HTTP Status Codes

Code	Meaning	MedConnect Behavior
200	Success	Process response normally
400	Bad Request	Fail with error message
401	Unauthorized	Fail (check Bearer token)
404	Not Found	Fail — endpoint URL is incorrect
408	Request Timeout	Retry (up to 2 additional attempts)
5xx	Server Error	Retry with exponential backoff

Transient errors (5xx, 408) trigger automatic retries with exponential backoff. Non-transient errors (4xx) fail immediately.

3. Reference Data

This section defines the standard code tables, enumerations, and data dictionaries used across the MedConnect API.

3.1 Sample Types

Value	Description
`EDTA`	EDTA anticoagulated whole blood
`Serum`	Serum (clotted blood, no anticoagulant)
`Plasma`	Plasma (heparin, citrate, etc.)
`Urine`	Urine sample
`CSF`	Cerebrospinal fluid
`Whole blood`	Whole blood (no anticoagulant)
`Other`	Other / unspecified

3.2 Test Mapping

Test mapping is the process of linking LIS test codes to instrument (device) test codes. This is a critical setup step.

Mapping Process:

MedConnect calls the Tests API to retrieve the LIS test catalog
The operator maps each LIS test to the corresponding instrument test in the MedConnect UI
This mapping is stored internally and used for converting test codes between LIS and instruments

4. Examples and Workflows

4.1 Interactive API Examples — Postman Collection

A complete, ready-to-use Postman Collection is provided alongside this document:

File: MedConnect_LIS_API.postman_collection.json

The collection includes every API endpoint with realistic request/response bodies, authentication headers, and environment variables.

⬇ Download Postman Collection

4.2 Complete Integration Workflow

The end-to-end integration follows four sequential steps:

Test Mapping — Retrieve Test Catalog: MedConnect calls the Tests API to retrieve the LIS test catalog. The operator then maps each LIS test to the corresponding instrument test.
Order Retrieval — Get Order by Barcode: When an instrument scans a barcode, MedConnect queries the LIS for order details.
Result Submission — Send Results to LIS: After the instrument completes testing, MedConnect submits results to the LIS.
Mark Order as Processed (Optional): Notify the LIS that the order has been accepted and processed by the instrument.