API Reference Overview

Welcome to the Kulcare API documentation. This guide provides comprehensive information about all available API endpoints, authentication, and best practices.

Base URLCopy Anchor Link

Production: https://api.kulcare.com
Staging: https://api-stg.kulcare.com
Development: http://localhost:3000

API VersionCopy Anchor Link

Current version: v1

All API endpoints are prefixed with the version number when applicable.

AuthenticationCopy Anchor Link

All API requests require authentication except for public endpoints (registration, login, etc.).

HeadersCopy Anchor Link

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
Accept: application/json

Profile ContextCopy Anchor Link

For multi-profile users, specify the active profile:

X-User-Account-Id: 456

Response FormatCopy Anchor Link

Success ResponseCopy Anchor Link

{
  "success": true,
  "data": {
    "id": 123,
    "type": "resource_type",
    "attributes": {
      // Resource attributes
    },
    "relationships": {
      // Related resources
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

Error ResponseCopy Anchor Link

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "phone_number": ["is invalid"],
      "email": ["has already been taken"]
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Paginated ResponseCopy Anchor Link

{
  "success": true,
  "data": [...],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 10,
      "total_count": 245,
      "per_page": 25,
      "next_page": 2,
      "prev_page": null
    }
  }
}

HTTP Status CodesCopy Anchor Link

Rate LimitingCopy Anchor Link

API requests are rate limited to ensure fair usage:

• Authenticated requests: 1000 requests per hour
• Unauthenticated requests: 60 requests per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642248000

PaginationCopy Anchor Link

List endpoints support pagination using query parameters:

GET /api/patients?page=2&per_page=50

Default values:

• page: 1
• per_page: 25 (max: 100)

FilteringCopy Anchor Link

Many endpoints support filtering via query parameters:

GET /api/appointments?status=scheduled&date=2024-01-15
GET /api/patients?search=john&city=Mumbai

SortingCopy Anchor Link

Use the sort parameter to sort results:

GET /api/patients?sort=created_at:desc
GET /api/appointments?sort=appointment_date:asc,created_at:desc

Field SelectionCopy Anchor Link

Limit returned fields using the fields parameter:

GET /api/patients?fields=id,name,phone_number

Including Related ResourcesCopy Anchor Link

Use the include parameter to include related resources:

GET /api/appointments?include=patient,doctor,clinic

API SectionsCopy Anchor Link

Core APIsCopy Anchor Link

• Authentication - User registration, login, verification
• Users & Profiles - User management and multi-profile system

Healthcare APIsCopy Anchor Link

• Clinics - Clinic management and settings
• Doctors - Doctor profiles and schedules
• Patients - Patient records and history
• Appointments - Appointment booking and management
• Medical Records - Prescriptions and medical documents

Business APIsCopy Anchor Link

• Billing - Payments, invoices, and subscriptions
• Reports - Analytics and reporting

Integration APIsCopy Anchor Link

• ABDM - Ayushman Bharat Digital Mission integration
• Webhooks - Event notifications

Error CodesCopy Anchor Link

Authentication ErrorsCopy Anchor Link

Validation ErrorsCopy Anchor Link

Business Logic ErrorsCopy Anchor Link

Request ExamplesCopy Anchor Link

cURLCopy Anchor Link

curl -X GET https://api.kulcare.com/api/patients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

JavaScript (Fetch)Copy Anchor Link

const response = await fetch('https://api.kulcare.com/api/patients', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

Python (Requests)Copy Anchor Link

import requests

headers = {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.kulcare.com/api/patients',
    headers=headers
)
data = response.json()

WebhooksCopy Anchor Link

Kulcare can send webhooks for various events:

{
  "event": "appointment.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "appointment_id": 123,
    "clinic_id": 456,
    "patient_id": 789
  }
}

See Webhooks Documentation for details.

SDK & LibrariesCopy Anchor Link

Official SDKs are available for:

• Ruby
• Python
• JavaScript/TypeScript
• PHP

Postman CollectionCopy Anchor Link

Import our Postman collection for easy API testing:

Download Postman Collection

API ChangelogCopy Anchor Link

Version 1.2 (2024-01-15)Copy Anchor Link

• Added multi-profile support
• Enhanced filtering capabilities
• Improved error responses

Version 1.1 (2023-12-01)Copy Anchor Link

• Added ABDM integration endpoints
• New appointment status workflow
• Performance improvements

Version 1.0 (2023-10-01)Copy Anchor Link

• Initial API release

SupportCopy Anchor Link

For API support:

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

Next StepsCopy Anchor Link

• Start with Authentication to get your API token
• Review endpoint documentation for your use case
• Check our Postman Collection for examples