Appearance
Analyzer Integration API
EaseLab accepts analyzer results via a dedicated integration endpoint. Devices authenticate with an API key and POST raw protocol payloads (HL7, ASTM, or JSON).
Integration endpoint
POST /integrations/v1/results
| Header | Required | Description |
|---|---|---|
X-Analyzer-Key | Yes | Device API key issued in tenant admin |
Content-Type | Yes | text/plain, application/hl7, or application/json |
Request body: Raw analyzer message (not JSON-wrapped).
Success response (200):
json
{
"message": "Results imported successfully.",
"barcode": "INV-2026-001234",
"resultsImported": 12,
"logId": "guid"
}Error responses:
| Status | Condition |
|---|---|
| 401 | Missing or invalid API key |
| 400 | Empty payload |
| 422 | Parse or matching failure (includes logId) |
GET /integrations/v1/health
Connectivity check with the same X-Analyzer-Key header:
json
{ "status": "ok", "device": "Chemistry Analyzer", "protocol": "Hl7" }Device management (tenant admin)
Configure devices via /lab/analyzers (requires plan feature + JWT):
| Method | Endpoint | Description |
|---|---|---|
| GET | /lab/analyzers | List devices |
| POST | /lab/analyzers | Create device (returns API key once) |
| DELETE | /lab/analyzers/{id} | Revoke device |
| GET | /lab/analyzers/logs | Ingestion logs |
Create device request
| Field | Description |
|---|---|
name | Display name |
protocol | Hl7, Astm, or Json |
description | Optional notes |
The API key is shown only at creation. Store it securely on the analyzer middleware PC.
Supported protocols
| Protocol | Content-Type | Notes |
|---|---|---|
| HL7 v2.x | application/hl7 or text/plain | ORU^R01 messages |
| ASTM | text/plain | E1394 records |
| JSON | application/json | EaseLab simplified format |
Result matching
The ingest service matches incoming results to invoices/samples by:
- Sample barcode in the message
- Patient ID or accession number
- Device-specific mapping rules
Unmatched results are logged with logId for troubleshooting. See Troubleshooting: Analyzers.
Plan requirements
Analyzer integration is a plan-gated feature. Tenants without the feature receive HTTP 403 from /lab/analyzers routes. The integration endpoint itself validates the API key regardless of plan (device must exist).
Network configuration
| Setting | Recommendation |
|---|---|
| Analyzer PC → API | HTTPS, outbound 443 |
| Firewall | Whitelist API server IP |
| Key rotation | Revoke old device, create new |
Example: cURL test
bash
curl -X POST https://api.example.com/integrations/v1/results \
-H "X-Analyzer-Key: your-device-key" \
-H "Content-Type: text/plain" \
--data-binary @result.hl7