The Docus Lab API is designed to streamline the interaction between medical laboratories and external systems by handling patient data, lab test results, AI-generated reports, and file attachments efficiently. Below is the structured flow describing how a lab interacts with the API.

1. Lab Conducts a Test and Sends Data to Docus Lab API

When a lab processes a patient's test, it collects and organizes biomarker data along with visit details (e.g., patient info, test date, and physician details).

📤 Lab sends a request to Docus Lab API:

Endpoint: POST /visits

Purpose: Registers a new visit and links it to a patient.

Response: 201 Created (if successful)

📤 Lab sends test results:

Endpoint: POST /lab-results

Purpose: Submits the biomarker values, LOINC codes, reference ranges, and clinical flags.

Response: 201 Created

📤 Lab uploads the original test report file (optional):

Endpoint: POST /attachments

Purpose: Uploads a PDF or other format test report.

Response: 201 Created

2. Docus Lab API Stores Data and Triggers AI Report Generation

After receiving the test results:

The API stores visit and test data in the database.

A background job is triggered to generate an AI-enhanced lab report.

This process may take a few minutes depending on system load and complexity.

The API acknowledges the request while processing the report asynchronously.

3. External System Checks AI Report Status

Since the AI report is not available immediately, external systems need to check its status periodically.

📥 Check if the AI-generated report is ready:

Endpoint: GET /lab-results/report/{visit_id}

Response:

If still processing: { "ready": false, "status": "Processing" }

If ready: { "ready": true, "status": "Completed", "report": { ... } }

4. External System Retrieves AI Report and Uses It

Once the AI report is ready, the system retrieves it for:

Displaying in a dashboard

Notifying the physician or lab technician

Integrating into a patient's medical record

📥 Retrieve AI-generated report:

Endpoint: GET /lab-results/report/{visit_id}

Response: JSON report with a summary, detailed findings, and recommendations

5. External System Retrieves Original Test Report (If Needed)

If the lab initially uploaded a PDF or other file, it can be retrieved:

📥 Retrieve lab report file:

Endpoint: GET /attachments/{visit_id}

Response: Returns a file URL for downloading

Summary of Workflow

Lab registers the visit (POST /visits)

Lab submits test results (POST /lab-results)

(Optional) Lab uploads test report file (POST /attachments)

Docus Lab API triggers AI report generation in the background

External system periodically checks report status (GET /lab-results/report/{visit_id})

Once ready, the AI report is retrieved

(Optional) External system downloads original lab test file (GET /attachments/{visit_id})

Benefits of Docus Lab API

Automated AI report generation – Reduces manual workload for physicians.

Asynchronous processing – API remains responsive while AI generates reports.

Secure and scalable – Handles large lab data sets efficiently.

Seamless integration – Works with external EHR, LIMS, and medical platforms.

This flow ensures faster lab report processing, improves decision-making, and reduces errors by leveraging AI-powered insights.

General flow

🚀 Docus Lab API helps labs and healthcare providers deliver better diagnostics with AI! 🔬 Let me know if you need adjustments!

Flow Between Lab and API

1. Lab Conducts a Test and Sends Data to Docus Lab API#

2. Docus Lab API Stores Data and Triggers AI Report Generation#

3. External System Checks AI Report Status#

4. External System Retrieves AI Report and Uses It#

5. External System Retrieves Original Test Report (If Needed)#

Summary of Workflow#

Benefits of Docus Lab API#

General flow#