Clinic APIs

APIs for managing clinic profiles, settings, locations, and staff members.

Overview

Clinic APIs handle all aspects of clinic management including profile setup, staff management, settings configuration, and multi-location support.

Base Path: /clinics

Authentication: Required for all endpoints

Profile Context: Must have clinic owner or admin role

Endpoints

Clinic Management

Get Clinic Profile

Retrieves the current clinic's profile information.

GET /clinics/:id

Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Clinic ID

Success Response:

{
  "success": true,
  "data": {
    "id": 123,
    "name": "City Health Clinic",
    "url": "city-health-clinic",
    "phone_number": "9876543210",
    "email": "info@cityhealthclinic.com",
    "address": "123 Main Street, Block A",
    "city": "Mumbai",
    "state": "Maharashtra",
    "country": "India",
    "pincode": "400001",
    "latitude": 19.0760,
    "longitude": 72.8777,
    "verified": true,
    "logo_url": "https://s3.amazonaws.com/...",
    "cover_photo_url": "https://s3.amazonaws.com/...",
    "bio": "Comprehensive healthcare services for the community",
    "specialities": ["General Medicine", "Pediatrics"],
    "facilities": ["Pharmacy", "Lab", "X-Ray"],
    "languages_spoken": ["English", "Hindi", "Marathi"],
    "insurance_accepted": ["Aditya Birla", "HDFC Ergo"],
    "timings": {
      "monday": {"start": "09:00", "end": "18:00"},
      "tuesday": {"start": "09:00", "end": "18:00"},
      "closed": ["sunday"]
    },
    "stats": {
      "total_doctors": 5,
      "total_patients": 1250,
      "total_appointments_today": 23,
      "rating": 4.5,
      "total_reviews": 89
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:20:00Z"
  }
}

Update Clinic Profile

Updates clinic profile information.

PUT /clinics/:id

Request Body:

{
  "clinic": {
    "name": "Updated Clinic Name",
    "email": "updated@clinic.com",
    "address": "New Address",
    "city": "New City",
    "pincode": "400002",
    "bio": "Updated clinic description",
    "phone_number": "9876543211"
  }
}

Success Response:

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Updated Clinic Name",
    // ... other clinic fields
  },
  "message": "Clinic updated successfully"
}

List User's Clinics

Gets all clinics associated with the current user.

GET /clinics

Query Parameters:

Parameter	Type	Description
role	string	Filter by user role: owner, consultant, staff
verified	boolean	Filter by verification status
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 25, max: 100)

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "City Health Clinic",
      "role": "owner",
      "city": "Mumbai",
      "verified": true,
      "total_patients": 1250,
      "logo_url": "https://..."
    },
    {
      "id": 124,
      "name": "District Hospital", 
      "role": "consultant",
      "city": "Pune",
      "verified": true,
      "total_patients": 2500,
      "logo_url": "https://..."
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 1,
      "total_count": 2,
      "per_page": 25
    }
  }
}

Create New Clinic

Creates a new clinic profile.

POST /clinics

Request Body:

{
  "clinic": {
    "name": "New Health Clinic",
    "phone_number": "9876543210",
    "email": "contact@newhealthclinic.com",
    "address": "456 Health Street",
    "city": "Chennai",
    "state": "Tamil Nadu",
    "country": "India",
    "pincode": "600001",
    "specialities": ["General Medicine"],
    "bio": "Quality healthcare for everyone"
  }
}

Success Response:

{
  "success": true,
  "data": {
    "id": 125,
    "name": "New Health Clinic",
    "verified": false,
    // ... other fields
  },
  "message": "Clinic created successfully"
}

Clinic Settings

Get Clinic Settings

Retrieves clinic configuration and preferences.

GET /clinics/:id/settings

Success Response:

{
  "success": true,
  "data": {
    "id": 456,
    "clinic_id": 123,
    "sms_enabled": true,
    "email_enabled": false,
    "whatsapp_enabled": true,
    "auto_confirm_appointments": false,
    "appointment_buffer_time": 5,
    "max_advance_booking_days": 30,
    "prescription_template": "Custom prescription header text",
    "bill_settings": {
      "auto_generate_bill": true,
      "include_consultation_fee": true,
      "tax_percentage": 18
    },
    "notification_settings": {
      "appointment_reminders": true,
      "payment_reminders": true,
      "feedback_requests": true
    },
    "business_hours": {
      "monday": {"open": "09:00", "close": "18:00", "closed": false},
      "tuesday": {"open": "09:00", "close": "18:00", "closed": false},
      "wednesday": {"open": "09:00", "close": "18:00", "closed": false},
      "thursday": {"open": "09:00", "close": "18:00", "closed": false},
      "friday": {"open": "09:00", "close": "18:00", "closed": false},
      "saturday": {"open": "09:00", "close": "14:00", "closed": false},
      "sunday": {"closed": true}
    }
  }
}

Update Clinic Settings

Updates clinic settings and preferences.

PUT /clinics/:id/settings

Request Body:

{
  "clinic_settings": {
    "sms_enabled": true,
    "email_enabled": true,
    "auto_confirm_appointments": true,
    "appointment_buffer_time": 10,
    "bill_settings": {
      "auto_generate_bill": true,
      "tax_percentage": 18
    },
    "business_hours": {
      "monday": {"open": "08:00", "close": "20:00"}
    }
  }
}

Staff Management

List Clinic Staff

Gets all staff members of the clinic.

GET /clinics/:id/staff

Query Parameters:

Parameter	Type	Description
role	string	Filter by role: doctor, staff, admin
active	boolean	Filter by active status
search	string	Search by name or phone

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 789,
      "user_id": 456,
      "name": "Dr. Sarah Johnson",
      "phone_number": "9876543211",
      "email": "sarah@clinic.com",
      "role": "doctor",
      "speciality": "Pediatrics",
      "active": true,
      "joined_at": "2024-01-10T09:00:00Z",
      "permissions": ["view_patients", "create_appointments", "manage_prescriptions"]
    },
    {
      "id": 790,
      "user_id": 457,
      "name": "Nurse Mary",
      "phone_number": "9876543212", 
      "role": "staff",
      "active": true,
      "joined_at": "2024-01-12T10:00:00Z",
      "permissions": ["view_patients", "create_appointments"]
    }
  ]
}

Invite Staff Member

Sends invitation to join clinic as staff member.

POST /clinics/:id/staff/invite

Request Body:

{
  "staff_invite": {
    "phone_number": "9876543213",
    "country_code": "91",
    "role": "staff",
    "permissions": ["view_patients", "create_appointments"],
    "message": "Join our clinic as a staff member"
  }
}

Success Response:

{
  "success": true,
  "data": {
    "invite_id": 101,
    "phone_number": "9876543213",
    "role": "staff",
    "status": "invited",
    "invited_at": "2024-01-21T15:30:00Z"
  },
  "message": "Invitation sent successfully"
}

Update Staff Member

Updates staff member role and permissions.

PUT /clinics/:id/staff/:staff_id

Request Body:

{
  "staff": {
    "role": "admin",
    "permissions": ["view_patients", "create_appointments", "manage_practice_finance"],
    "active": true
  }
}

Remove Staff Member

Removes staff member from clinic.

DELETE /clinics/:id/staff/:staff_id

Success Response:

{
  "success": true,
  "message": "Staff member removed successfully"
}

Clinic Locations

List Clinic Locations

Gets all locations for a multi-location clinic.

GET /clinics/:id/locations

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 301,
      "name": "Main Branch",
      "address": "123 Main Street",
      "city": "Mumbai",
      "pincode": "400001",
      "phone_number": "9876543210",
      "is_primary": true,
      "latitude": 19.0760,
      "longitude": 72.8777
    },
    {
      "id": 302,
      "name": "Branch Office",
      "address": "456 Branch Road",
      "city": "Mumbai", 
      "pincode": "400002",
      "phone_number": "9876543214",
      "is_primary": false,
      "latitude": 19.0850,
      "longitude": 72.8950
    }
  ]
}

Add New Location

Adds a new location to the clinic.

POST /clinics/:id/locations

Request Body:

{
  "location": {
    "name": "New Branch",
    "address": "789 New Street", 
    "city": "Mumbai",
    "pincode": "400003",
    "phone_number": "9876543215"
  }
}

Update Location

Updates clinic location information.

PUT /clinics/:id/locations/:location_id

Delete Location

Removes a clinic location.

DELETE /clinics/:id/locations/:location_id

Clinic Services

List Services

Gets all services offered by the clinic.

GET /clinics/:id/services

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 501,
      "name": "General Consultation",
      "category": "consultation", 
      "price": 500,
      "duration": 15,
      "description": "General medical consultation",
      "active": true
    },
    {
      "id": 502,
      "name": "Blood Test - CBC",
      "category": "lab_test",
      "price": 300,
      "description": "Complete Blood Count test",
      "active": true
    }
  ]
}

Add Service

Adds a new service to the clinic.

POST /clinics/:id/services

Request Body:

{
  "service": {
    "name": "ECG Test",
    "category": "diagnostic",
    "price": 200,
    "duration": 10,
    "description": "Electrocardiogram test"
  }
}

Update Service

Updates clinic service information.

PUT /clinics/:id/services/:service_id

Delete Service

Removes a service from the clinic.

DELETE /clinics/:id/services/:service_id

Analytics & Reports

Clinic Dashboard

Gets clinic dashboard statistics.

GET /clinics/:id/dashboard

Query Parameters:

Parameter	Type	Description
period	string	Time period: today, week, month, year
start_date	date	Custom start date (YYYY-MM-DD)
end_date	date	Custom end date (YYYY-MM-DD)

Success Response:

{
  "success": true,
  "data": {
    "overview": {
      "total_patients": 1250,
      "new_patients_this_month": 45,
      "total_appointments_today": 23,
      "pending_appointments": 8,
      "completed_appointments_today": 15,
      "revenue_today": 12500,
      "revenue_this_month": 185000
    },
    "appointments": {
      "scheduled": 35,
      "confirmed": 28,
      "completed": 142,
      "cancelled": 12,
      "no_show": 3
    },
    "popular_services": [
      {"name": "General Consultation", "count": 89},
      {"name": "Blood Test", "count": 34}
    ],
    "doctor_performance": [
      {
        "doctor_id": 101,
        "name": "Dr. Smith",
        "appointments_today": 12,
        "revenue_today": 6000,
        "rating": 4.8
      }
    ]
  }
}

Revenue Report

Gets detailed revenue analytics.

GET /clinics/:id/reports/revenue

Query Parameters:

Parameter	Type	Description
start_date	date	Report start date
end_date	date	Report end date
group_by	string	Group by: day, week, month

Success Response:

{
  "success": true,
  "data": {
    "total_revenue": 185000,
    "revenue_breakdown": {
      "consultations": 120000,
      "procedures": 45000,
      "lab_tests": 20000
    },
    "daily_revenue": [
      {"date": "2024-01-15", "amount": 8500},
      {"date": "2024-01-16", "amount": 12000}
    ],
    "top_services": [
      {"service": "General Consultation", "revenue": 120000},
      {"service": "Blood Test", "revenue": 20000}
    ]
  }
}

Patient Analytics

Gets patient-related analytics.

GET /clinics/:id/reports/patients

Error Responses

Common Error Codes

Code	Status	Description
CLINIC_NOT_FOUND	404	Clinic not found
UNAUTHORIZED_CLINIC_ACCESS	403	User doesn't have access to this clinic
CLINIC_VALIDATION_ERROR	422	Invalid clinic data
STAFF_INVITE_FAILED	422	Failed to send staff invitation
LOCATION_LIMIT_EXCEEDED	422	Maximum locations reached
SERVICE_ALREADY_EXISTS	422	Service with same name exists

Example Error Response

{
  "success": false,
  "error": {
    "code": "CLINIC_VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "name": ["is too short (minimum is 2 characters)"],
      "phone_number": ["has invalid format"]
    }
  }
}

Webhooks

Clinic-related webhooks:

clinic.created - New clinic registered
clinic.updated - Clinic profile updated
clinic.verified - Clinic verification completed
staff.joined - Staff member joined clinic
location.added - New location added

Examples

Complete Clinic Setup Flow

# 1. Create clinic
curl -X POST https://api.kulcare.com/clinics \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clinic": {
      "name": "My Health Clinic",
      "phone_number": "9876543210",
      "city": "Mumbai"
    }
  }'

# 2. Update settings
curl -X PUT https://api.kulcare.com/clinics/123/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clinic_settings": {
      "sms_enabled": true,
      "auto_confirm_appointments": true
    }
  }'

# 3. Invite staff
curl -X POST https://api.kulcare.com/clinics/123/staff/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "staff_invite": {
      "phone_number": "9876543211",
      "role": "staff"
    }
  }'

Rate Limits

Clinic profile updates: 10 per hour
Staff invitations: 20 per day
Settings updates: 30 per hour
Dashboard/reports: 100 per hour

Next Steps

Doctor APIs - Manage doctor profiles
Patient APIs - Patient management
Appointment APIs - Booking system

Clinic APIs

OverviewCopy Anchor Link

EndpointsCopy Anchor Link

Clinic ManagementCopy Anchor Link

Get Clinic ProfileCopy Anchor Link

Update Clinic ProfileCopy Anchor Link

List User's ClinicsCopy Anchor Link

Create New ClinicCopy Anchor Link

Clinic SettingsCopy Anchor Link

Get Clinic SettingsCopy Anchor Link

Update Clinic SettingsCopy Anchor Link

Staff ManagementCopy Anchor Link

List Clinic StaffCopy Anchor Link

Invite Staff MemberCopy Anchor Link

Update Staff MemberCopy Anchor Link

Remove Staff MemberCopy Anchor Link

Clinic LocationsCopy Anchor Link

List Clinic LocationsCopy Anchor Link

Add New LocationCopy Anchor Link

Update LocationCopy Anchor Link

Delete LocationCopy Anchor Link

Clinic ServicesCopy Anchor Link

List ServicesCopy Anchor Link

Add ServiceCopy Anchor Link

Update ServiceCopy Anchor Link

Delete ServiceCopy Anchor Link

Analytics & ReportsCopy Anchor Link

Clinic DashboardCopy Anchor Link

Revenue ReportCopy Anchor Link

Patient AnalyticsCopy Anchor Link

Error ResponsesCopy Anchor Link

Common Error CodesCopy Anchor Link

Example Error ResponseCopy Anchor Link

WebhooksCopy Anchor Link

ExamplesCopy Anchor Link

Complete Clinic Setup FlowCopy Anchor Link

Rate LimitsCopy Anchor Link

Next StepsCopy Anchor Link

On this page

Overview

Endpoints

Clinic Management

Get Clinic Profile

Update Clinic Profile

List User's Clinics

Create New Clinic

Clinic Settings

Get Clinic Settings

Update Clinic Settings

Staff Management

List Clinic Staff

Invite Staff Member

Update Staff Member

Remove Staff Member

Clinic Locations

List Clinic Locations

Add New Location

Update Location

Delete Location

Clinic Services

List Services

Add Service

Update Service

Delete Service

Analytics & Reports

Clinic Dashboard

Revenue Report

Patient Analytics

Error Responses

Common Error Codes

Example Error Response

Webhooks

Examples

Complete Clinic Setup Flow

Rate Limits

Next Steps