Docus CDS API (Labs)
    Docus CDS API (Labs)
    • Getting Started
    • Submit Lab Results
      POST
    • Generate Interpretation
      POST
    • Access URL Delivery
      POST

    Getting Started

    This guide explains how to integrate with the Docus API to submit medical data, generate interpretation reports, and provide secure access for patients and/or physicians.
    The integration is asynchronous and supports different workflows depending on how the partner lab operates.

    Overview of the Flow#

    1.
    Submit lab results
    2.
    Store results under a visit/order (reference_id)
    3.
    Receive temporary access links
    4.
    Trigger interpretation report generation
    5.
    Access the generated report in the Docus interface

    Configuration#

    During onboarding, the partner lab chooses how they work with reports:
    Patients only — generate patient-facing reports and set up the patient interface
    Physicians only — generate doctor-facing reports and set up the physician interface
    Both patients and physicians — generate both report types and set up both patient and physician interfaces
    Based on this configuration:
    patient_email becomes mandatory if patient-facing reports are required.
    physician_email becomes mandatory if doctor-facing reports are required.
    User accounts are automatically created for the provided email addresses, allowing access to the Docus interface.

    Step 1 — Submit Lab Results#

    Partners submit lab results to Docus via the Submit Lab Results request.
    Each request includes:
    patient_id — Unique identifier of the patient
    reference_id — Identifier of the patient’s visit, order, or group of tests for which interpretation reports should be generated.
    patient_email — Optional by default, mandatory if patient-facing reports and patient interface are required.
    physician_email — Optional by default, mandatory if doctor-facing reports and physician interface are required.
    data and/or file_base64 — The main payload containing laboratory results.
    At least one of data or file_base64 must be provided.
    Even if the lab submits results only via files, it is highly recommended to include any important data not present in the file in the data field.
    All results belonging to the same visit or order must use the same reference_id.

    Step 2 — Group Results by Visit or Order#

    Multiple results can be submitted for the same visit or order.
    To associate them correctly, use the same reference_id for each submission.
    Docus stores all submitted results and waits until report generation is triggered.
    As a result, one interpretation report will be generated based on all lab results grouped under the same reference_id.

    Step 3 — Receive Access Links#

    When Docus receives a new lab result (creating a new visit using reference_id), it automatically sends temporary access links to the partner system via the Access URL Delivery request.
    The response may include one or two links depending on the partner configuration:
    patient_access_url
    physician_access_url
    These links are designed to provide quick and easy access to the interface. They:
    Provide direct access to the visit page
    Are valid for 14 days
    Redirect to the login page after expiration
    Users can also log in to the Docus interface using their email addresses.

    Step 4 — Trigger Report Generation#

    Once all lab results for the visit or order have been submitted, partners trigger report generation via the Generate Report request.
    This request includes:
    patient_id
    reference_id
    After receiving this request, Docus starts generating the appropriate interpretation reports based on the partner configuration:
    Patient-facing report
    Physician-facing report
    Or both

    Authentication#

    Requests from Partner to Docus#

    All requests to Docus must include the following headers:
    x-api-key
    x-team-id
    These credentials are provided during onboarding.

    Requests from Docus to Partner#

    Docus sends access URLs to the partner-provided endpoint.
    Requests are authenticated using the x-api-key provided by the partner during integration.

    Error Handling#

    All endpoints use standard HTTP status codes.
    It is recommended to implement a retry mechanism for temporary failures (for example, network errors or timeouts).

    Important Notes#

    Use the same reference_id for all test results belonging to the same visit or order.
    Trigger report generation only after all results for the visit/order have been submitted.
    The generated interpretation report will include all results grouped under the same reference_id.
    Treat reference_id as the primary identifier for the visit or order.

    Support#

    For onboarding assistance or integration questions, contact:
    support@docus.ai
    Next
    Submit Lab Results
    Built with