Lab System Integration API

How LISBridge sends data to your lab system

Every time the LISBridge desktop app parses a result from a connected instrument, it forwards that result to a server you control with a single HTTP POST. The destination is the Base URL you enter in LISBridge, with the fixed path /api/lis-data appended — so LISBridge always posts to {baseUrl}/api/lis-data. There is no polling and no SDK: your lab system just needs an endpoint at that path that accepts JSON.

This page documents exactly what LISBridge sends, what your endpoint should return, and includes a working receiver you can copy into your own project.

{
  "raw_data": "H|\\^&|||Sysmex^XN-1000|||||||P|1\rO|1|S20260522-014||^^^CBC\r...",
  "client_ip": "192.168.1.50",
  "token": "987654321",
  "parsed_data": {
    "order_id": "S20260522-014",
    "machine_name": "Sysmex XN-1000",
    "findings": [
      { "parameter": "WBC", "value": "6.5",  "unit": "10^3/uL" },
      { "parameter": "HGB", "value": "14.2", "unit": "g/dL" },
      { "parameter": "PLT", "value": "250",  "unit": "10^3/uL" }
    ]
  }
}

{ "status": "success", "saved": 3 }

// app/api/lis-data/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const body = await request.json();

  // 1. parsed_data is only present when LISBridge parsed the message
  const parsed = body.parsed_data;
  if (!parsed) {
    // Parse failed upstream — keep raw_data for review, then acknowledge
    // await saveRaw(body.raw_data, body.client_ip);
    return NextResponse.json({ status: "received", saved: 0 }, { status: 200 });
  }

  // 2. Persist each finding
  const rows = parsed.findings.map((f: { parameter: string; value: string; unit: string | null }) => ({
    order_id: parsed.order_id,
    machine_name: parsed.machine_name, // may be null
    parameter: f.parameter,
    value: f.value,
    unit: f.unit,                      // may be null
    client_ip: body.client_ip,
  }));
  // await db.machineTestResult.createMany({ data: rows });

  return NextResponse.json(
    { status: "success", saved: rows.length },
    { status: 200 },
  );
}

const express = require('express');
const app = express();
app.use(express.json({ limit: '10mb' })); // images can be large

app.post('/api/lis-data', (req, res) => {
  const { client_ip, parsed_data } = req.body;

  // 1. parsed_data is absent on parse failure
  if (!parsed_data) {
    return res.status(200).json({ status: 'received', saved: 0 });
  }

  // 2. Store findings
  const { order_id, machine_name, findings } = parsed_data;
  for (const f of findings) {
    // INSERT INTO results (order_id, machine_name, parameter, value, unit, client_ip)
    console.log(`${order_id} ${machine_name ?? '?'} ${f.parameter}=${f.value} ${f.unit ?? ''}`);
  }

  res.status(200).json({ status: 'success', saved: findings.length });
});

app.listen(3001, () => console.log('Listening on :3001  POST /api/lis-data'));

<?php
header('Content-Type: application/json');

$body = json_decode(file_get_contents('php://input'), true);

// 1. parsed_data may be absent on parse failure
$parsed = $body['parsed_data'] ?? null;
if (!$parsed) {
    http_response_code(200);
    echo json_encode(['status' => 'received', 'saved' => 0]);
    exit;
}

// 2. Store findings
$orderId = $parsed['order_id'];
$machine = $parsed['machine_name'] ?? null;   // may be null
foreach ($parsed['findings'] as $f) {
    $parameter = $f['parameter'];
    $value     = $f['value'];
    $unit      = $f['unit'] ?? null;          // may be null
    // $stmt->execute([$orderId, $machine, $parameter, $value, $unit, $body['client_ip']]);
}

http_response_code(200);
echo json_encode(['status' => 'success', 'saved' => count($parsed['findings'])]);

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/lis-data', methods=['POST'])
def lis_data():
    body = request.get_json()

    # 1. parsed_data is absent on parse failure
    parsed = body.get('parsed_data')
    if not parsed:
        return jsonify({'status': 'received', 'saved': 0}), 200

    # 2. Store findings
    order_id = parsed['order_id']
    machine  = parsed.get('machine_name')      # may be None
    for f in parsed['findings']:
        parameter = f['parameter']
        value     = f['value']
        unit      = f.get('unit')              # may be None
        # db.execute('INSERT INTO results ...',
        #            (order_id, machine, parameter, value, unit, body.get('client_ip')))

    return jsonify({'status': 'success', 'saved': len(parsed['findings'])}), 200

if __name__ == '__main__':
    app.run(port=3001)

POST http://<device-ip>:<port>/api/orders
Content-Type: application/json
X-LISBridge-Token: <your-token>

{
  "his_order_id":       "ORD-2026-00142",   // required — idempotency key
  "target_instrument":  "Horiba Yumizen",   // required — instrument name or model key
  "specimen_id":        "S20260628-001",    // required — barcode / sample ID
  "specimen_type":      "BLOOD",            // optional
  "patient_id":         "PA001",            // optional
  "patient_first_name": "John",             // optional
  "patient_last_name":  "Doe",             // optional
  "patient_gender":     "M",               // optional  "M" | "F" | "U"
  "patient_dob":        "19900115",         // optional  YYYYMMDD
  "priority":           "R",               // optional  "R" = routine | "S" = STAT
  "action":             "NW",              // optional  "NW" | "CA" | "RP" (default: NW)
  "referred_by":        "DR001",           // optional
  "profiles": [                            // optional — omit for fixed-panel instruments
    { "code": "CBC",  "name": "CBC" },
    { "code": "DIFF", "name": "Differential" }
  ],
  "max_attempts": 3                        // optional — delivery retry cap (default: 3)
}

// 202 Accepted
{
  "id": 42,
  "his_order_id": "ORD-2026-00142",
  "status": "pending",
  "created": true
}

const order = {
  his_order_id: "ORD-2026-00142",
  target_instrument: "Horiba Yumizen",
  specimen_id: "S20260628-001",
  specimen_type: "BLOOD",
  patient_id: "PA001",
  patient_first_name: "John",
  patient_last_name: "Doe",
  priority: "R",
};

const res = await fetch("http://192.168.1.55:8765/api/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-LISBridge-Token": process.env.LISBRIDGE_TOKEN,
  },
  body: JSON.stringify(order),
});

if (res.status === 202) {
  const ref = await res.json();
  console.log("Order queued:", ref.id, ref.his_order_id);
} else {
  const err = await res.json();
  console.error("Order rejected:", err.error);
}

import requests, os

order = {
    "his_order_id": "ORD-2026-00142",
    "target_instrument": "Horiba Yumizen",
    "specimen_id": "S20260628-001",
    "specimen_type": "BLOOD",
    "patient_id": "PA001",
    "priority": "R",
}

resp = requests.post(
    "http://192.168.1.55:8765/api/orders",
    json=order,
    headers={"X-LISBridge-Token": os.environ["LISBRIDGE_TOKEN"]},
    timeout=10,
)

if resp.status_code == 202:
    ref = resp.json()
    print("Queued:", ref["id"], ref["his_order_id"])
else:
    print("Rejected:", resp.json().get("error"))

<?php
$order = [
    'his_order_id'       => 'ORD-2026-00142',
    'target_instrument'  => 'Horiba Yumizen',
    'specimen_id'        => 'S20260628-001',
    'specimen_type'      => 'BLOOD',
    'patient_id'         => 'PA001',
    'priority'           => 'R',
];

$ch = curl_init('http://192.168.1.55:8765/api/orders');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($order),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-LISBridge-Token: ' . getenv('LISBRIDGE_TOKEN'),
    ],
]);

$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code === 202) {
    $ref = json_decode($body, true);
    echo "Queued: " . $ref['id'] . " " . $ref['his_order_id'];
} else {
    echo "Rejected: " . json_decode($body, true)['error'];
}

POST https://your-his.example.com/api/orders/poll
Content-Type: application/json
x-lisbridge-token: <your-secret-token>

// POST body LISBridge sends on each poll
{
  "source":    "LISBridge",
  "device_id": "abc123-device-uuid",
  "ack": [
    {
      "his_order_id": "ORD-2026-001",   // the ID you sent in the previous response
      "lis_id":       42,               // LISBridge internal order ID (store for debugging)
      "status":       "recorded",       // "recorded" | "duplicate" | "rejected"
      "error":        null              // non-null only when status = "rejected"
    }
  ]
}

// 200 OK — your endpoint responds with pending orders
{
  "orders": [
    {
      "his_order_id":      "ORD-2026-002",   // required — stable unique ID from your HIS
      "target_instrument": "Sysmex XN-550",  // required — must match an instrument in LISBridge
      "priority":          "ROUTINE",        // optional — "ROUTINE" | "URGENT" (default: ROUTINE)
      "patient": {                           // optional — included in the order message
        "id":     "P-10045",
        "name":   "Ahmed Rahman",
        "age":    34,
        "gender": "M"                        // "M" | "F" | "U"
      },
      "tests": ["CBC", "WBC DIFF"]           // optional — test/profile codes
    }
  ]
}

const express = require("express");
const app = express();
app.use(express.json());

const TOKEN = process.env.LISBRIDGE_PULL_TOKEN; // set this to match LISBridge config

app.post("/api/orders/poll", (req, res) => {
  // 1. Validate token
  if (req.headers["x-lisbridge-token"] !== TOKEN) {
    return res.status(401).json({ error: "unauthorized" });
  }

  // 2. Process acks from the previous poll
  for (const a of req.body.ack ?? []) {
    if (a.status === "recorded" || a.status === "duplicate") {
      db.markOrderFulfilled(a.his_order_id); // your HIS logic here
    } else if (a.status === "rejected") {
      console.error("Order rejected:", a.his_order_id, a.error);
    }
  }

  // 3. Respond with pending orders
  const pending = db.getPendingOrders({ limit: 500 }); // your HIS query here
  res.json({
    orders: pending.map(o => ({
      his_order_id:      o.id,
      target_instrument: o.instrument,
      priority:          o.urgent ? "URGENT" : "ROUTINE",
      patient: { id: o.patientId, name: o.patientName, age: o.age, gender: o.gender },
      tests:             o.testCodes,
    })),
  });
});

app.listen(3000);