SmartVaxAI - HIPAA Compliant Vaccination Processing

SmartVaxAI API Integration

This documentation is for EHR vendors to integrate with the SmartVaxAI platform through our secure API endpoints. Our API allows you to process and extract data from vaccination cards and submit it to EHR systems.

Authentication

All API requests require the following authentication:

API Key Header:x-api-key
Bearer Token:Authorization: Bearer your-token

x-api-key: your-api-key-here
Authorization: Bearer your-token-here

Base URL

All API endpoints are accessible at this GCP Cloud Run URL:

https://smartvax-api-new-730874408505.us-central1.run.app

API Endpoints Overview

Endpoint	Method	Purpose	URL
Health Check	GET	Verify API availability	/health
Submit Record	POST	Submit vaccination data	/api/vaccinations
Process Vaccination	POST	Process vaccination card with AI	/api/ehr/process-vaccination
Submit to EHR	POST	Submit to EHR system	/api/ehr/submit-vaccination
Process & Send	POST	Combined process and send	/api/ehr/process-send
Batch Status	GET	Get batch processing status	/api/batch/status
Flush Batches	POST	Force process all pending batches	/api/batch/flush

NEW: Batch Processing

Our API now supports batch processing for improved efficiency when submitting multiple vaccination records.

Benefits of Batch Processing:

Reduced API calls to EHR systems
Lower network overhead and better performance
Optimized throughput for large volumes of records
Automatic grouping by healthcare organization

How It Works:

When batch processing is enabled, records submitted to /api/vaccinations are automatically:

Grouped by site ID and EHR vendor
Held until batch size threshold or time limit is reached
Processed in optimized batches for better performance
Submitted to EHR systems with compression for large batches

Submit Vaccination Record

Submit vaccination card data with optional image for processing:

Endpoint:

POST/api/vaccinations

Header Requirements:

x-api-key: Your API key
Content-Type: application/json
x-test-run-id: Optional tracking ID for testing

Request Body:

{
  "patientFirstName": "John",               // Required
  "patientLastName": "Doe",                 // Required
  "patientDOB": "1980-01-01",               // Required, ISO date format
  "vaccineName": "COVID-19 Vaccine",        // Required
  "vaccineDate": "2023-05-15",              // Vaccination date (also accepts administration_date)
  "vaccineLocation": "City Medical Center", // Optional
  "healthcare_professional": "Dr. Smith",   // Optional
  "userId": "user-id-123",                  // Required - User ID for tracking
  "organizationId": "org-id-456",           // Required - Organization ID
  "status": "pending",                      // Optional - valid values: "pending", "verified"
  "notes": "First dose",                    // Optional
  "imageData": "data:image/jpeg;base64,..." // Optional but recommended - Base64 encoded image
}

Response:

{
  "status": "accepted",
  "message": "Vaccination record queued for processing",
  "supabaseId": "f7c051c3-3c08-45d1-a1a4-32b07b7c2d3a",
  "imageUrl": "https://example.com/storage/vaccination_images/path/to/image.jpg",
  "messageId": "12345678901234"
}

Image Processing:

When you include imageData in your request, the API performs these steps:

Stores the image in Supabase Storage in the vaccination_images bucket
Creates a record in the vaccination_images table with metadata
Associates the image with the vaccination record via image_id
The image can be retrieved using the returned imageUrl

Status Field Values:

The API accepts the following status values. All other values will be automatically mapped to one of these:

pending: Initial state, record is awaiting verification
verified: Record has been verified and is ready for EHR submission
submitted: Record has been submitted to an EHR system
error: An error occurred during processing

Note: The API internally maps similar status values (e.g., "processed" maps to "verified") for flexibility.

Database Schema

Understanding the database schema is essential for successful integration:

vaccination_records Table:

Field	Type	Description
id	UUID	Primary key
patient_first_name	TEXT	Patient's first name
patient_last_name	TEXT	Patient's last name
patient_birthdate	DATE	Patient's date of birth
vaccine_name	TEXT	Name of the vaccine
administration_date / vaccine_date	DATE	Date of vaccination (supports both field names)
healthcare_professional	TEXT	Name of healthcare professional
healthcare_organization	TEXT	Name of healthcare facility
image_id	UUID	Reference to vaccination_images table
status	TEXT	Record status (pending, verified, submitted, error)

vaccination_images Table:

Field	Type	Description
id	UUID	Primary key
user_id	TEXT	User ID who uploaded the image
organization_id	UUID	Organization ID
storage_path	TEXT	Path to image in Supabase Storage
original_filename	TEXT	Original filename
mime_type	TEXT	MIME type of the image
ocr_status	TEXT	OCR processing status
ocr_data	JSONB	Extracted data from OCR processing

Troubleshooting

Common Issues:

Status Value Not Accepted

If you're getting errors related to the status field, ensure you're using one of the supported values: "pending", "verified", "submitted", or "error". The API will attempt to map similar values but explicit values are preferred.

Image Not Appearing

If the image is not appearing in the dashboard:

Ensure the image data is correctly formatted as a Data URL (data:image/jpeg;base64,...)
Verify that the image size is reasonable (under 10MB)
Check that your API key has the proper permissions for image storage

API Key Issues

If you receive authentication errors, verify your API key is correctly included in the header as "x-api-key". For access or permission issues, contact the SmartVaxAI team at support@smartvaxai.com.

API Test Console

You can test the API endpoints directly from your development environment using the examples above.

Select Endpoint

API Key

Next Steps

Request API credentials from your SmartVaxAI representative
Implement integration following the examples above
Test your integration with sample vaccination cards
Contact support@smartvaxai.com if you need assistance