Overview

Complete integration guide for third-party healthcare systems to integrate with ZautoAI platform.

The ZautoAI Integration API provides secure access to healthcare data management functionality. The API is designed for:

  • Hospital Management Systems (HMS)
  • Electronic Health Record (EHR) systems
  • Practice Management Software
  • Third-party healthcare applications

Authentication Flow

ZautoAI uses OAuth 2.0 Client Credentials flow for API authentication.

Step 1: Get Client Credentials

Contact your ZautoAI administrator to generate client credentials. You'll receive:

  • client_id: Format zauto_<name>_<hex8>
  • client_secret: Format zauto_<hex64>
⚠️ Important: Store credentials securely. The secret cannot be retrieved again.

Step 2: Obtain Access Token

Endpoint: POST /api/auth/oAuth/token

POST /api/auth/oAuth/token HTTP/1.1
Host: api.zautoai.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "zauto_hospital_a1b2c3d4",
  "client_secret": "zauto_1234567890abcdef..."
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 3: Use Access Token

Include the access token in all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Endpoints

All endpoints use the base path /zauto-api and require Bearer authentication.

Response Format

All API responses follow this structure:

{
  "status": "success" | "error",
  "message": "Human readable message",
  "data": { /* Response data */ },
  "pagination": { /* Only for list endpoints */ }
}

Pagination Format

{
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 47,
    "hasNext": true,
    "hasPrev": false
  }
}

Standard Query Parameters

  • page: Page number (default: 1)
  • limit: Items per page (default: 10, max: 100)
  • search: Search term (case-insensitive)

Patients API

Create Patient

Endpoint: POST /zauto-api/patients

Required Fields

  • id (string): Your system's patient ID
  • uhid (number): Unique Hospital ID number
  • fullName (string): Patient's full name
  • phoneNumber (string): Contact phone number

Request Example

{
  "id": "ext-patient-001",
  "uhid": 12345,
  "uhidPrefix": "ZAI",
  "fullName": "John Doe",
  "title": "Mr.",
  "dateOfBirth": "1990-05-15",
  "email": "john.doe@email.com",
  "gender": "Male",
  "phoneNumber": "+1234567890",
  "bloodGroup": "O+",
  "aadhaarNumber": "123456789012",
  "whatsappNumber": "+1234567890",
  "preferred_lang": "en",
  "address": "123 Healthcare St, Medical City, MC 12345",
  "emergencyContactName": "Jane Doe",
  "emergencyContactRelation": "Spouse",
  "emergencyContactPhone": "+1234567891",
  "insuranceProvider": "Health Insurance Co",
  "insurancePolicyNumber": "POL123456",
  "medicalHistory": "Diabetes, Hypertension",
  "remarks": "Regular checkup patient",
  "isTeleCommunication": false,
  "visited": false,
  "referredBy": "Dr. Smith"
}

Response (201 Created)

{
  "status": "success",
  "message": "Patient created successfully",
  "data": {
    "id": "internal-uuid-123",
    "externalId": "ext-patient-001",
    "fullName": "John Doe",
    "uhid": 12345,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
Get All Patients

Endpoint: GET /zauto-api/patients

Query Parameters

  • page: Page number (default: 1)
  • limit: Items per page (default: 10, max: 100)
  • search: Search in fullName, phoneNumber, email, externalId, uhid

Example Request

GET /zauto-api/patients?page=1&limit=20&search=john
Authorization: Bearer <token>
Get Patient by ID

Endpoint: GET /zauto-api/patients/{id}

Parameters: id - External patient ID

Update Patient

Endpoint: PUT /zauto-api/patients/{id}

All fields are optional in update requests.

Delete Patient

Endpoint: DELETE /zauto-api/patients/{id}

Patient Visits API

Enums

PatientType: "IN_PATIENT" | "OUT_PATIENT" | "ONE_DAY_SERVICE" | "EMERGENCY"
VisitStatus: "IN_QUEUE" | "IN_PROGRESS" | "IN_REVIEW" | "FINISHED" | "COMPLETED" | "NO_SHOW" | "CANCELED"
Create Patient Visit

Endpoint: POST /zauto-api/patient-visits

Required Fields

  • id: External visit ID
  • patientId: External patient ID (must exist)
  • visitDateTime: ISO 8601 datetime string

Request Example

{
  "id": "ext-visit-001",
  "patientId": "ext-patient-001",
  "visitDateTime": "2024-01-15T14:30:00Z",
  "tokenNumber": 45,
  "providerId": "ext-provider-001",
  "patientType": "OUT_PATIENT",
  "dischargeDateTime": "2024-01-15T16:30:00Z",
  "purposeOfVisit": "Regular checkup and blood pressure monitoring",
  "status": "IN_QUEUE"
}
Get All Patient Visits

Endpoint: GET /zauto-api/patient-visits

Search Fields: purposeOfVisit, externalId, patient.fullName, provider.fullName

Ordering: visitDateTime (descending)

Other Resources

Specialities

Base: /zauto-api/specialities

Required Fields

  • id: External speciality ID
  • name: Speciality name
POST /zauto-api/specialities
GET  /zauto-api/specialities?page=1&limit=10&search=cardio
GET  /zauto-api/specialities/{id}
PUT  /zauto-api/specialities/{id}
DELETE /zauto-api/specialities/{id}
Facilities

Base: /zauto-api/facilities

Required Fields

  • id: External facility ID
  • name: Facility name
Providers

Base: /zauto-api/providers

Required Fields

  • id: External provider ID
  • fullName: Provider's full name
Medicines

Base: /zauto-api/medicines

Required Fields

  • id: External medicine ID
  • name: Medicine name
Services

Base: /zauto-api/services

Required Fields

  • id: External service ID
  • name: Service name
  • description: Service description

Push to Partner Endpoint

ZautoAI can push order data to partner endpoints using the payload formats below.

Prescription Orders

Payload sent when prescriptions are issued for a visit.

{
  "externalVisitId": "string",
  "Medications": [
    {
      "externalMedicineId": "string",
      "name": "string",
      "dose": "string",
      "when": "string",
      "frequency": "string",
      "duration": "string",
      "notes": "string"
    }
  ]
}

Service Orders

Payload sent when services are scheduled or updated for a visit.

{
  "externalVisitId": "string",
  "Services": [
    {
      "externalServiceId": "string",
      "name": "string",
      "price": 300,
      "status": "string"
    }
  ]
}

Notes

  • All externalId fields refer to the HIS ID (the ID from your Hospital Information System).
  • If your endpoint requires any authentication (e.g., API key, token, etc.), please let us know so that we can configure it accordingly.

Error Handling

HTTP Status Codes

  • 200: Success
  • 201: Created
  • 400: Bad Request (validation errors)
  • 401: Unauthorized (invalid/expired token)
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found
  • 409: Conflict (duplicate external ID)
  • 429: Too Many Requests (rate limit exceeded)
  • 500: Internal Server Error

Error Response Format

{
  "status": "error",
  "message": "Human readable error message",
  "errors": [
    {
      "field": "fieldName",
      "message": "Field-specific error message"
    }
  ],
  "errorCode": "SPECIFIC_ERROR_CODE",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

  • INVALID_TOKEN: Access token is invalid or expired
  • VALIDATION_FAILED: Request validation failed
  • RESOURCE_NOT_FOUND: Requested resource doesn't exist
  • DUPLICATE_EXTERNAL_ID: External ID already exists
  • REFERENCED_RESOURCE_NOT_FOUND: Referenced entity doesn't exist
  • RATE_LIMIT_EXCEEDED: API rate limit exceeded

Rate Limiting

  • Rate Limit: 1000 requests per hour per client
  • Burst Limit: 100 requests per minute
  • Headers: Rate limit information is returned in response headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

Integration Examples

Node.js Example
const axios = require('axios');

class ZautoAIClient {
  constructor(clientId, clientSecret, baseUrl = 'https://api.zautoai.com') {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.baseUrl = baseUrl;
    this.accessToken = null;
    this.refreshToken = null;
  }

  async authenticate() {
    try {
      const response = await axios.post(`${this.baseUrl}/api/auth/oAuth/token`, {
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret
      });

      this.accessToken = response.data.access_token;
      this.refreshToken = response.data.refresh_token;
      
      // Set token expiration timer
      setTimeout(() => {
        this.refreshAccessToken();
      }, (response.data.expires_in - 60) * 1000);

      return response.data;
    } catch (error) {
      throw new Error(`Authentication failed: ${error.response?.data?.error_description || error.message}`);
    }
  }

  getHeaders() {
    return {
      'Authorization': `Bearer ${this.accessToken}`,
      'Content-Type': 'application/json'
    };
  }

  async createPatient(patientData) {
    const response = await axios.post(
      `${this.baseUrl}/zauto-api/patients`,
      patientData,
      { headers: this.getHeaders() }
    );
    return response.data;
  }

  async getPatients(page = 1, limit = 10, search = '') {
    const params = new URLSearchParams({ page, limit, search });
    const response = await axios.get(
      `${this.baseUrl}/zauto-api/patients?${params}`,
      { headers: this.getHeaders() }
    );
    return response.data;
  }

  async createPatientVisit(visitData) {
    const response = await axios.post(
      `${this.baseUrl}/zauto-api/patient-visits`,
      visitData,
      { headers: this.getHeaders() }
    );
    return response.data;
  }
}

// Usage example
async function main() {
  const client = new ZautoAIClient(
    'zauto_hospital_a1b2c3d4',
    'zauto_1234567890abcdef...'
  );

  try {
    // Authenticate
    await client.authenticate();
    console.log('Authentication successful');

    // Create a patient
    const patientData = {
      id: 'ext-patient-12345',
      uhid: 98765,
      fullName: 'Alice Johnson',
      phoneNumber: '+1234567890',
      email: 'alice.johnson@email.com',
      gender: 'Female'
    };

    const createResponse = await client.createPatient(patientData);
    console.log('Patient created:', createResponse.data);

    // Create a patient visit
    const visitData = {
      id: 'ext-visit-67890',
      patientId: 'ext-patient-12345',
      visitDateTime: new Date().toISOString(),
      purposeOfVisit: 'Annual checkup',
      patientType: 'OUT_PATIENT'
    };

    const visitResponse = await client.createPatientVisit(visitData);
    console.log('Visit created:', visitResponse.data);

  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();
Python Example
import requests
import json
from datetime import datetime

class ZautoAIClient:
    def __init__(self, client_id, client_secret, base_url="https://api.zautoai.com"):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = base_url
        self.access_token = None
        self.refresh_token = None

    def authenticate(self):
        url = f"{self.base_url}/api/auth/oAuth/token"
        data = {
            "grant_type": "client_credentials",
            "client_id": self.client_id,
            "client_secret": self.client_secret
        }
        
        response = requests.post(url, json=data)
        response.raise_for_status()
        
        token_data = response.json()
        self.access_token = token_data["access_token"]
        self.refresh_token = token_data["refresh_token"]
        
        return token_data

    def get_headers(self):
        return {
            "Authorization": f"Bearer {self.access_token}",
            "Content-Type": "application/json"
        }

    def create_patient(self, patient_data):
        url = f"{self.base_url}/zauto-api/patients"
        response = requests.post(url, json=patient_data, headers=self.get_headers())
        response.raise_for_status()
        return response.json()

    def get_patients(self, page=1, limit=10, search=""):
        url = f"{self.base_url}/zauto-api/patients"
        params = {"page": page, "limit": limit, "search": search}
        response = requests.get(url, params=params, headers=self.get_headers())
        response.raise_for_status()
        return response.json()

# Usage
client = ZautoAIClient("zauto_hospital_a1b2c3d4", "zauto_1234567890abcdef...")
client.authenticate()

# Create patient
patient = {
    "id": "ext-patient-54321",
    "uhid": 11111,
    "fullName": "Bob Wilson",
    "phoneNumber": "+1987654321",
    "gender": "Male"
}

result = client.create_patient(patient)
print(f"Patient created: {result['data']['externalId']}")
PowerShell Example
# Authentication
$authBody = @{
    grant_type = "client_credentials"
    client_id = "zauto_hospital_a1b2c3d4"
    client_secret = "zauto_1234567890abcdef..."
} | ConvertTo-Json

$authResponse = Invoke-RestMethod -Method Post -Uri "https://api.zautoai.com/api/auth/oAuth/token" -Body $authBody -ContentType "application/json"
$token = $authResponse.access_token

# Create patient
$headers = @{
    "Authorization" = "Bearer $token"
    "Content-Type" = "application/json"
}

$patientData = @{
    id = "ext-patient-99999"
    uhid = 55555
    fullName = "Charlie Brown"
    phoneNumber = "+1555123456"
    email = "charlie.brown@email.com"
} | ConvertTo-Json

$patientResponse = Invoke-RestMethod -Method Post -Uri "https://api.zautoai.com/zauto-api/patients" -Headers $headers -Body $patientData

Write-Host "Patient created: $($patientResponse.data.externalId)"

Testing

Test Data

Use these test records for integration testing:

Test Patient
{
  "id": "test-patient-001",
  "uhid": 99999,
  "fullName": "Test Patient",
  "phoneNumber": "+1234567890",
  "email": "test@example.com"
}
Test Provider
{
  "id": "test-provider-001",
  "fullName": "Dr. Test Provider",
  "email": "testprovider@example.com"
}
Test Visit
{
  "id": "test-visit-001",
  "patientId": "test-patient-001",
  "visitDateTime": "2024-01-15T14:30:00Z",
  "purposeOfVisit": "Test visit"
}

Sandbox Environment

  • Base URL: https://dev-api.zautoai.com
  • Separate client credentials will be provided for testing
  • Test data is reset nightly

Support

For technical support and questions:

  • Email: api-support@zautoai.com
  • Documentation: https://docs.zautoai.com
  • Status Page: https://status.zautoai.com

SLA & Uptime

  • Uptime: 99.9% guaranteed
  • Response Time: < 200ms for 95% of requests
  • Support Response: 24 hours for technical issues

Last updated: September 2024 • API Version: 1.4.7