> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Parsed Report Result

> Use this API with the document_id to fetch results. This endpoint returns a JSON response that includes a detailed and structured parsed report.

* **Processing Time:** Record parsing typically takes 1–2 minutes for documents up to 10 pages and 2–4 minutes for those exceeding 10 pages, depending on the document size.
* **Understanding the Components of Response**
  * ## Lab Report

    ### Lab test

    Every lab test will have:

    * `test_name` : Verbatim as written in the lab report

    * `test_eka_id` : Eka identifier for the test

    * `loinc_id` : LOINC identifier for the test

    * NOTE: we use method agnostic LOINC identifiers in majority of the lab tests. Mapping of all Eka identifiers with LOINC identifiers can be obtained from [here](https://www.notion.so/EkaCare-Lab-report-parsing-details-16f28b1d375d8002918efa88d0d46567?pvs=21).

    ### Lab test data (value | unit | range)

    Lab test observation is parsed and shared in two variants

    ### Non unit-normalised data (`data` )

    This data is not unit-normalised, meaning this is verbatim as written in the report. The keys comprise

    * `value` : value of the test as given in the report
    * `unit` : unit of the test as given in the report, parsed by OCR (Non post processed). NOTE: at times OCR reads 10^3 u/ml as 103u/ml
    * `unit_processed` : unit of the test as given in the report, parsed by OCR and then processed by eka. In the above example 103u/ml  is converted back to 10\*3u/ml after applying post processing
    * `normal_range_report` : normal range parsed object basis the low-high values given in the report
    * `normal_range_eka` : normal range parsed object basis EkaCare’s database considering age / gender information of the person from the report.
    * `unit_eka_id` : Eka id for unit
    * `display_range` : Verbatim range display text (string) parsed from the report.

    ### Unit-Normalised data (`normalised_data` )

    This object contains unit normalised data for Value, Unit and range objects mentioned above. Normalisation is explained in detailed in the subsequent section.

    This object contains all the fields mentioned above except `display_range` and `unit_processed`since that is verbatim and normalisation does not make sense.

    # Normalisation process

    In order to create longitudinal lab investigation trends across lab reports across time, one needs to convert lab values and ranges to a standard unit. For every lab test, EkaCare defines a standard unit (basis highest frequency across millions of records). List of standard units for every test can be found [here](https://www.notion.so/EkaCare-Lab-report-parsing-details-16f28b1d375d8002918efa88d0d46567?pvs=21). Normalisation is process of multiplying values and normal ranges with a factor that converts the numerical results in the report to EkaCare standard unit for that lab test.

    # Range-object

    Range objects contain structured low and high values of the normal range.

    Note that our parsers only structured low-high normal range format. Any other formats such as:

    normal: \< 200
    borderline high: 200-240
    high: 240+

    While this data is available in “display\_range” field in non unit-normalised object as string, we do not parse and structure this kind of structure.

    However, EkaCare ranges in structured formats are available for someone to still interpret the results if need be.

    # PII data

    This section outlines the structure and components of Personally Identifiable Information (PII) as provided within medical documentation. The information captured includes page number, document dates, patient details, and report specifics.

    ### Components of PII Data

    `<unique_file_path>`: A unique identifier representing the file path is utilized to group related PII information. Each file path is mapped to a collection of PII data for different pages in the document..

    * `PageNum`**:** Represents the page number within the document where relevant PII data is found.
    * `DocumentDate`**:** Captures the document date in Unix timestamp format for consistent time-related operations.

    ### **Patient Details**

    * `Name`**:** Verbatim representation of the patient's name as found in the document.
    * `Age`**:** The patient's age is detailed in years, months, and days, providing a comprehensive age identification.
    * `Gender`**:** Captures the patient's gender, e.g., "male" or "female".

    ### **Report Details**

    * `SampleCollectionDate`**:** (only for Lab-reports) The date and time when the sample was collected, in "dd/mm/yyyy hh:mm:ss" format.
    * `SampleReceivedDate`**:** (only for Lab-reports) The date and time when the sample was received, in "dd/mm/yyyy hh:mm:ss" format.
    * `GeneratedDate`**:** (only for Lab-reports) The report generation date and time in "dd/mm/yyyy hh:mm:ss" format.
    * `Doctor`**:** The doctor's name, if available.
    * `Facility`**:** The name of the facility or laboratory where the test was conducted, e.g., "LalPath Labs".


## OpenAPI

````yaml get /mr/api/v1/docs/{document_id}/result
openapi: 3.0.0
info:
  title: Document Upload API
  description: API to pre-sign the URL for uploading documents.
  version: 1.0.0
  license:
    name: Proprietary License
    url: https://developer.eka.care/license
servers:
  - url: https://api.eka.care
    description: Production server
  - url: https://api.dev.eka.care
    description: Development server
security: []
tags:
  - name: Records
    description: API related to records document management.
paths:
  /mr/api/v1/docs/{document_id}/result:
    get:
      tags:
        - Records
      description: This API is check the parsing status of the uploaded document
      operationId: getResult
      parameters:
        - in: path
          name: document_id
          required: true
          description: Document ID to update the document details.
          schema:
            type: string
            example: 2df9e795-d368-4ceb-be9d-b44281703827
        - name: X-Pt-Id
          in: header
          schema:
            type: string
          description: eka user id (OID)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileProcessingResponse'
        '400':
          description: Bad request
        '500':
          description: Internal server error
      security:
        - auth: []
components:
  schemas:
    FileProcessingResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - queued
            - inprogress
            - completed
            - deleted
            - error
          description: The current status of the request.
        error:
          type: array
          items:
            type: object
            properties:
              code:
                type: integer
                description: Error code.
              message:
                type: string
                description: Error message.
        data:
          type: object
          properties:
            fhir:
              type: string
              format: byte
              description: Base64 encoded FHIR data.
            output:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      test_name:
                        type: string
                        description: Name of the test.
                      data:
                        type: object
                        properties:
                          value:
                            type: number
                            description: Measured value of the test.
                          unit:
                            type: string
                            description: Original unit.
                          unit_processed:
                            type: string
                            description: Processed unit.
                          normal_range_report:
                            type: string
                            description: JSON string of normal range as reported.
                          normal_range_eka:
                            type: string
                            description: JSON string of normal range for Eka.
                          unit_eka_id:
                            type: string
                            description: Eka ID for the unit.
                          display_range:
                            type: string
                            description: Displayed range.
                      normalised_data:
                        type: object
                        properties:
                          value:
                            type: number
                            description: Normalized value.
                          unit:
                            type: string
                            description: Normalized unit.
                          normal_range_report:
                            type: string
                            description: JSON string of normalized range as reported.
                          normal_range_eka:
                            type: string
                            description: JSON string of normalized range for Eka.
                          unit_eka_id:
                            type: string
                            description: Eka ID for the normalized unit.
                      confidence:
                        type: number
                        description: Confidence level in the test data.
                      test_eka_id:
                        type: string
                        description: Eka ID for the test.
                      loinc_id:
                        type: string
                        description: LOINC ID of the test.
                pii:
                  type: object
                  additionalProperties:
                    type: array
                    items:
                      type: object
                      properties:
                        PageNum:
                          type: integer
                          description: Page number in the document.
                        DocumentDate:
                          type: integer
                          format: int64
                          description: Epoch timestamp of the document date.
                        Patient:
                          type: object
                          properties:
                            Age:
                              type: object
                              properties:
                                Years:
                                  type: integer
                                  description: Age in years.
                                Months:
                                  type: integer
                                  description: Age in months.
                                Days:
                                  type: integer
                                  description: Age in days.
                            Gender:
                              type: string
                              description: Gender of the patient.
                            Name:
                              type: string
                              description: Name of the patient.
                        Report:
                          type: object
                          properties:
                            SampleCollectionDate:
                              type: string
                              format: date-time
                              description: Date and time of sample collection.
                            SampleReceivedDate:
                              type: string
                              format: date-time
                              description: Date and time the sample was received.
                            GeneratedDate:
                              type: string
                              format: date-time
                              description: Date and time the report was generated.
                            Doctor:
                              type: string
                              description: Name of the doctor associated with the report.
                            Facility:
                              type: string
                              description: Name of the facility generating the report.
  securitySchemes:
    auth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````