API Integration Specification
This document summarizes the API contract currently used for the diagnostic integration. It covers authentication, order submission, cancellation, result retrieval, health check, and a developer/testing endpoint.
1. API Overview
API | Method | Endpoint | Purpose |
Health Check | GET | /api/v1/integrations/ping/ | Check API availability |
Login | POST | /api/v1/integrations/login/ | Authenticate and obtain tokens |
Refresh Token | POST | /api/v1/integrations/getAccessToken/ | Generate a new access token |
Submit Order | POST | /api/v1/integrations/orders/ | Submit a diagnostic order |
Fetch Result | POST | /api/v1/integrations/orders/result/ | Fetch result/status |
Cancel Order | POST | /api/v1/integrations/orders/cancel/ | Cancel an order |
2. Authentication
POST /api/v1/integrations/login/
Header: Content-Type: application/json
Request:
{"username":"<username>","password":"<password>"}
Response:
{"Result":"Success","Data":{"accessToken":"<access-token>","refreshToken":"<refresh-token>","tokenType":"Bearer","expiresIn":3600},"Message":"Login successful"}
Protected APIs use: Authorization: Bearer <access-token>
3. Refresh Access Token
POST /api/v1/integrations/getAccessToken/
Header: Content-Type: application/json
Request:
{"refresh":"<refresh-token>"}
Response:
{"Result":"Success","Data":{"access":"<new-access-token>"},"Message":"Successfully issued new access token"}
4. Submit Order
POST /api/v1/integrations/orders/
Headers: Content-Type: application/json; Authorization: Bearer <access-token>
Request:
{
"externalPatientId": "70419864919",
"externalVisitId": "809414",
"externalOrderId": "71014264917-1108411-MTB",
"orderType": "XRAY_CHEST",
"orderedAt": "2026-07-30T11:24:21.601541186+05:30",
"patient": {
"firstName": "SEE",
"lastName": "XCC",
"dateOfBirth": "2007-07-27",
"sex": "Other"
}
}
Example response when the order already exists:
{
"Result": "Success",
"Data": {
"externalPatientId": "70419864919",
"externalVisitId": "809414",
"externalOrderId": "71014264917-1108411-MTB",
"orderType": "XRAY_CHEST",
"status": "CANCELLED"
},
"Message": "Order already exists"
}
Request Field Meaning
| Field | Meaning |
|---|---|
externalPatientId | Beneficiary ID provided in the request. It uniquely identifies the beneficiary/patient in the system. |
externalVisitId | Visit code/ID associated with the beneficiary's particular visit. |
externalOrderId | Unique order ID for the beneficiary's diagnostic order. This should uniquely identify the order in the system. |
orderType | Type of diagnostic investigation being ordered, e.g. XRAY_CHEST. |
5. Fetch Result
POST /api/v1/integrations/orders/result/
Headers: Content-Type: application/json; Authorization: Bearer <access-token>
Request:
{"externalOrderId":"7101426497-108411-MTB","includeAssets":"none"}
Example response when the result is not yet available:
{
"Result": "Success",
"Data": {
"externalOrderId": "432016521926-558343-XRAY_CHEST",
"orderType": "XRAY_CHEST",
"status": "COMPLETED",
"components": {
"xray": {
"status": "COMPLETED"
},
"cad": {
"status": "COMPLETED",
"provider": "DRONGOAI"
}
},
"result": {
"summary": "Abnormal but not TB Presumptive",
"rawJson": {
"OrderId": 367,
"results": {
"result": "Abnormal but not TB Presumptive",
"image": "/media/abnormal/abnormal/abnormal.png",
"findings": [
{
"name": "Tuberculosis",
"presence": false,
"confidence": 0.139
},
{
"name": "Cardiomegaly",
"presence": true,
"confidence": 0.6
},
{
"name": "Pleural Thickening",
"presence": true,
"confidence": 0.623
},
{
"name": "Pleural Effusion",
"presence": true,
"confidence": 0.706
},
{
"name": "Pneumothorax",
"presence": false,
"confidence": 0.169
},
{
"name": "Consolidation",
"presence": false,
"confidence": 0.291
},
{
"name": "Atelectasis",
"presence": false,
"confidence": 0.22
},
{
"name": "Nodule Mass",
"presence": false,
"confidence": 0.41
},
{
"name": "Fibrosis",
"presence": false,
"confidence": 0.324
},
{
"name": "Infiltration",
"presence": false,
"confidence": 0.321
},
{
"name": "Calcification",
"presence": false,
"confidence": 0.214
}
],
"metadata": {
"version": null,
"patient_id": "131",
"sop_instance_uid": "1.2.826.auto.312.abnormal"
}
}
},
"reportedAt": "2026-09-23T09:34:34.775599+00:00",
"assets": []
}
},
"Message": "Result fetched successfully"
}
6. Cancel Order
POST /api/v1/integrations/orders/cancel/
Headers: Content-Type: application/json; Authorization: Bearer <access-token>
Request:
{"externalOrderId":"71014264917-1108411-MTB","reason":"Patient Refused"}
Example response:
{
"Result": "Success",
"Data": {
"externalOrderId": "71014264917-1108411-MTB",
"currentStatus": "Cancelled"
},
"Message": "Order is already cancelled"
}
7. Health Check
GET /api/v1/integrations/ping/
No request body is shown in the provided example.
Response:
{"Result":"Success","Data":{},"Message":"pong"}
8. Developer / Testing API
POST /api/v1/integrations/result-push/
This endpoint is for developer/testing purposes to simulate a result push.
Headers: Content-Type: application/json; Authorization: Bearer <access-token>
Request:
{"orderID":"432016521926-558343-XRAY_CHEST","result":"abnormal"}
Response:
{
"Result": "Success",
"Data": {
"status": "Abnormal but not TB Presumptive",
"cadOrderId": 367
},
"Message": "X-Ray and CAD report completed successfully via manual push"
}
9. Integration Flow
Health Check → Login → Submit Order → Fetch/Poll Result → Result Available. Cancel Order is used when cancellation is required.
10. Points to Confirm with LG
Final endpoint URLs for LG environments (UAT/Production).
Authentication mechanism and credential exchange.
Supported order types and required fields.
Order status values and result status values.
Result payload, including X-ray/CAD report and asset handling.
Cancellation rules and supported cancellation reasons.
Error response format, HTTP status codes, timeout and retry expectations.