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"
}

5. Fetch Result

POST /api/v1/integrations/orders/result/

Headers: Content-Type: application/json; Authorization: Bearer <access-token>

Request:

{"externalOrderId":"7101426497-108411-MTB","includeAssets":"base64"}

Example response when the result is not yet available:

{
"Result": "Success",
"Data": {
"externalOrderId": "7101426497-108411-MTB",
"orderType": "XRAY_CHEST",
"status": "IN_PROGRESS",
"components": {
"xray": {"status": "PENDING"},
"cad": {"status": "PENDING", "provider": ""}
},
"result": null
},
"Message": "Result is not available yet"
}

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