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: Formatzauto_<name>_<hex8>client_secret: Formatzauto_<hex64>
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 IDuhid(number): Unique Hospital ID numberfullName(string): Patient's full namephoneNumber(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 IDpatientId: 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 IDname: 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 IDname: Facility name
Providers
Base: /zauto-api/providers
Required Fields
id: External provider IDfullName: Provider's full name
Medicines
Base: /zauto-api/medicines
Required Fields
id: External medicine IDname: Medicine name
Services
Base: /zauto-api/services
Required Fields
id: External service IDname: Service namedescription: 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
externalIdfields 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 expiredVALIDATION_FAILED: Request validation failedRESOURCE_NOT_FOUND: Requested resource doesn't existDUPLICATE_EXTERNAL_ID: External ID already existsREFERENCED_RESOURCE_NOT_FOUND: Referenced entity doesn't existRATE_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: 1642248000Integration 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