Mobile App API Specification

Base URL: https://zeus.intelms.com:8447 Timeout: 30 seconds Content-Type: application/json

---

Authentication

Login

Endpoint: POST /api/v1/sessions

Headers:

Content-Type: application/json

Request Body:

{
  "username": "string",
  "password": "string"
}

Success Response (200 OK):

{
  "auth_token": "string",
  "user": {
    "name": "string",
    "description": "string",
    "roles": ["array"]
  }
}

Mobile Implementation:

• Store token as: "Bearer " + response.auth_token
• Storage key: "TOKEN" in AsyncStorage
• Token expires: 24 hours

Error Responses:

• 401 Unauthorized - Invalid credentials
• 500 Internal Server Error - Server error

---

Lab Reports

All report endpoints require authentication.

Authentication Header:

Authorization: Bearer {auth_token}

---

Get All Reports

Endpoint: GET /api/v1/reports

Headers:

Authorization: Bearer {auth_token}
Content-Type: application/json

Query Parameters: None (returns all accessible reports)

Success Response (200 OK):

{
  "reports": [
    {
      "id": "integer",
      "collection": "datetime (ISO 8601)",
      "received": "datetime (ISO 8601)",
      "subject": "string",
      "doctor": "string",
      "specimen": "string",
      "folder": "string",
      "report_status": "string",
      "department": "string",
      "text_only": "boolean",
      "report_tests": "array (if text_only=false)",
      "result_date": "datetime (if text_only=false)",
      "summary": "string (if text_only=true)",
      "body_text": "string",
      "patient": {
        "id": "integer",
        "first_name": "string",
        "last_name": "string",
        "date_of_birth": "date (YYYY-MM-DD)",
        "sex": "string",
        "medical_record_number": "string"
      },
      "studies": "array",
      "meta": {
        "next_report_id": "integer",
        "prev_report_id": "integer",
        "report_total": "integer",
        "report_index": "integer"
      }
    }
  ],
  "current_page": "integer",
  "next_page": "integer",
  "prev_page": "integer",
  "total_pages": "integer",
  "total_count": "integer"
}

Mobile Transformation:

• Calculate age from patient.date_of_birth
• Create full_name: first_name + " " + last_name
• Create header_title: "{full_name} | {age} | {sex} | {DOB}"
• Group reports by received date
• Format dates as DD/MM/YYYY

Error Responses:

• 401 Unauthorized - Invalid/expired token
• 403 Forbidden - Access denied
• 500 Internal Server Error - Server error

---

Get Unread Reports

Endpoint: GET /api/v1/reports?read=false

Headers:

Authorization: Bearer {auth_token}
Content-Type: application/json

Query Parameters:

• read=false - Filter for unread reports only

Success Response: Same structure as "Get All Reports"

Filtering Logic:

• Returns reports where status = 0 (Not Read)
• Only reports addressed to authenticated user
• Excludes superseded reports

---

Get Marked Reports

Endpoint: GET /api/v1/reports?marked=true

Headers:

Authorization: Bearer {auth_token}
Content-Type: application/json

Query Parameters:

• marked=true - Filter for marked reports only

Success Response: Same structure as "Get All Reports"

Filtering Logic:

• Returns reports marked by user
• User-specific marking state

---

Get DNR Reports

Endpoint: GET /api/v1/reports?dnr_only=true

Headers:

Authorization: Bearer {auth_token}
Content-Type: application/json

Query Parameters:

• dnr_only=true - Filter for Do Not Report (DNR) only

Success Response: Same structure as "Get All Reports"

Filtering Logic:

• Returns DNR flagged reports
• Critical/flagged results

---

Get Single Report

Endpoint: GET /api/v1/reports/{id}?patient_id={patient_id}

Headers:

Authorization: Bearer {auth_token}
Content-Type: application/json

URL Parameters:

• id - Report ID (integer)

Query Parameters:

• patient_id - Patient ID (integer, required)

Success Response (200 OK):

{
  "id": "integer",
  "collection": "datetime (ISO 8601)",
  "received": "datetime (ISO 8601)",
  "subject": "string",
  "doctor": "string",
  "specimen": "string",
  "folder": "string",
  "report_status": "string",
  "department": "string",
  "text_only": "boolean",
  "report_tests": "array",
  "result_date": "datetime",
  "summary": "string",
  "body_text": "string",
  "patient": {
    "id": "integer",
    "first_name": "string",
    "last_name": "string",
    "date_of_birth": "date",
    "sex": "string",
    "medical_record_number": "string"
  },
  "studies": "array",
  "drug_order": "object",
  "referral": "object",
  "consultation": "object",
  "meta": {
    "next_report_id": "integer",
    "prev_report_id": "integer",
    "report_total": "integer",
    "report_index": "integer"
  }
}

Side Effect:

• Viewing report marks it as read (updates status)

Error Responses:

• 401 Unauthorized - Invalid/expired token
• 403 Forbidden - No access to this report
• 404 Not Found - Report doesn't exist
• 500 Internal Server Error - Server error

---

Search Reports

Endpoint: GET /api/v1/reports

Headers:

Authorization: Bearer {auth_token}
Content-Type: application/json

Query Parameters (all optional):

• first_name - Patient first name (string)
• last_name - Patient last name (string)
• date - Date filter (date)
• status - "Not Read" or "Read" (string)
• text_only - Filter text reports only (boolean)
• page - Page number for pagination (integer)

Success Response: Same structure as "Get All Reports"

---

Error Handling

Network Errors:

• Message: "No Internet Connection Found!"
• Occurs when no network connectivity

Timeout Errors:

• Message: "Internet connection is poor"
• Occurs after 30 seconds

Session Expired:

• Message: "Session expired. Please login again"
• Occurs when token is invalid/expired
• Action: Redirect to login screen

---

Common Response Fields

Report Object

Field	Type	Description
id	integer	Unique report identifier
collection	datetime	Sample collection date/time
received	datetime	Report received date/time
subject	string	Report subject/title
doctor	string	Ordering physician
specimen	string	Specimen type
folder	string	Report category/folder
report_status	string	Status (Final, Preliminary, etc.)
department	string	Department (Microbiology, Histology, etc.)
text_only	boolean	true = text report, false = lab results
report_tests	array	Lab test results (when text_only=false)
result_date	datetime	Result date (when text_only=false)
summary	string	Report summary (when text_only=true)
body_text	string	Full report body
patient	object	Patient demographics
studies	array	Radiology images (if applicable)
meta	object	Navigation metadata

Patient Object

Field	Type	Description
id	integer	Patient identifier
first_name	string	Patient first name
last_name	string	Patient last name
date_of_birth	date	DOB (YYYY-MM-DD)
sex	string	Patient sex
medical_record_number	string	MRN

Pagination Metadata

Field	Type	Description
current_page	integer	Current page number
next_page	integer	Next page number (null if last)
prev_page	integer	Previous page number (null if first)
total_pages	integer	Total number of pages
total_count	integer	Total number of reports

---

Implementation Notes

Mobile App Responsibilities

1. Token Management:

   • Store token with "Bearer " prefix
   • Include in Authorization header for all authenticated requests
   • Clear token and redirect to login on 401 errors

2. Data Transformation:

   • Calculate patient age from date_of_birth
   • Create full_name from first_name + last_name
   • Format header_title with patient details
   • Group reports by received date
   • Format dates as DD/MM/YYYY for display

3. Report Grouping:

   • Group by received date
   • Sort by newest first
   • Format group headers with date

4. Error Handling:

   • Network errors: Show offline message
   • Timeout: Show poor connection message
   • 401: Clear session and return to login
   • Other errors: Show generic error message

Backend Behavior

1. Access Control:

   • Ward users: See reports for their ward + direct assignments
   • Hospital users: See reports for entire organization
   • All users: Superseded reports excluded by default

2. Status Updates:

   • Viewing report (GET /api/v1/reports/:id) marks as read
   • Status changes reflect immediately in subsequent requests

3. Date Filtering:

   • Default: 7 days before last admission
   • Doctors: 1 year from inbox
   • Uses collection_date, report_date, or created_at

4. Pagination:

   • Default page size configured server-side
   • Use page parameter for navigation
   • Total count provided for UI