Medos SDK

A JavaScript/TypeScript SDK for integrating healthcare appointment booking into your applications. Built for clinics, hospitals, and healthcare platforms.

Installation

npm install medos-sdk

Getting Started

Authentication

The SDK supports two authentication methods:

Server-Side (API Key)

Use this method for backend services and server-side rendering.

import { MedosClient } from 'medos-sdk';

await MedosClient.init({
  apiKey: 'your-api-key',
  baseURL: 'https://api-dev.medapi.in/v1'
});

Client-Side (Session Token)

Use this method for frontend applications. Obtain the session token from your backend.

import { MedosClient } from 'medos-sdk';

await MedosClient.initWithSession({
  sessionToken: 'user-session-token',
  baseURL: 'https://api-dev.medapi.in/v1'
});

Usage

Fetch Clinic Addresses and Doctors

Retrieve all available clinic locations with their associated doctors.

const result = await MedosClient.fetchAllAddressesAndDoctors();

Response:

{
  totalAddresses: 5,
  totalDoctors: 12,
  workspaceId: "workspace-123",
  addresses: [
    {
      id: "addr-1",
      completeAddress: "123 Medical Center, New York, NY 10001",
      addressLine1: "123 Medical Center",
      city: "New York",
      state: "NY",
      country: "USA",
      zipcode: "10001",
      doctors: [
        {
          id: "doc-1",
          name: "Dr. John Smith",
          email: "john.smith@example.com",
          specialty: "Cardiology"
        }
      ]
    }
  ]
}

Fetch Available Slots

Get available appointment time slots for a specific doctor.

const slots = await MedosClient.fetchAppointments(
  'workspace-123',  // workspaceId
  'addr-1',        // addressId
  'doc-1',         // doctorId
  '2025-11-16'     // appointmentDate (YYYY-MM-DD)
);

Response:

[
  {
    start: "2025-11-16T10:00:00",
    end: "2025-11-16T10:30:00",
    id: "slot-1"
  },
  {
    start: "2025-11-16T11:00:00",
    end: "2025-11-16T11:30:00",
    id: "slot-2"
  }
]

Book an Appointment

Create a new appointment booking.

import { AppointmentService } from 'medos-sdk';

const appointment = await AppointmentService.createAppointment({
  workspaceAddressId: 'addr-1',
  doctorId: 'doc-1',
  mode: 'OFFLINE',
  appointmentDate: '2025-11-16',
  fromDateTimeTs: '10:00',
  toDateTimeTs: '10:30',
  consultationCharge: '100',
  type: 'CONSULTATION',
  source: 'SDK_POWERED_WEBSITE',
  patientPayload: {
    firstName: 'Jane',
    lastName: 'Doe',
    email: 'jane.doe@example.com',
    countryCode: '+1',
    phoneNumber: '5551234567',
    age: 30,
    gender: 'FEMALE'
  },
  patientAddress: {
    addressLine1: '456 Patient Street',
    city: 'New York',
    state: 'NY',
    country: 'USA',
    zipcode: '10001',
    landmark: 'Near Central Park'
  }
});

Optional Fields:

Phone Verification

Implement OTP-based phone number verification for patients.

Send OTP

await MedosClient.sendPhoneVerificationOtp({
  countryCode: '+1',
  phoneNumber: '5551234567'
});

Verify OTP

const result = await MedosClient.verifyPhoneVerificationOtp({
  countryCode: '+1',
  phoneNumber: '5551234567',
  otp: '123456'
});

TypeScript

The SDK is written in TypeScript and provides comprehensive type definitions.

import {
  MedosClient,
  AppointmentService,
  BookAppointmentPayload,
  AddressesResponse,
  PatientPayload,
  PatientAddressPayload
} from 'medos-sdk';

const payload: BookAppointmentPayload = {
  workspaceAddressId: 'addr-1',
  doctorId: 'doc-1',
  appointmentDate: '2025-11-16',
  fromDateTimeTs: '10:00',
  toDateTimeTs: '10:30',
  patientPayload: {
    firstName: 'John',
    lastName: 'Doe',
    countryCode: '+1',
    phoneNumber: '5551234567'
  },
  patientAddress: {
    addressLine1: '123 Main Street',
    city: 'New York',
    state: 'NY',
    country: 'USA',
    zipcode: '10001'
  }
};

const appointment = await AppointmentService.createAppointment(payload);

Type Definitions

BookAppointmentPayload

{
  workspaceAddressId: string | number;
  doctorId: string | number;
  appointmentDate: string;           // Format: "YYYY-MM-DD"
  fromDateTimeTs: string;            // Format: "HH:MM"
  toDateTimeTs: string;              // Format: "HH:MM"
  mode?: "OFFLINE" | "ONLINE";       // Default: "OFFLINE"
  consultationCharge?: string;       // Default: "0"
  type?: "CONSULTATION" | string;    // Default: "CONSULTATION"
  source?: string;                   // Default: "SDK_POWERED_WEBSITE"
  patientPayload: PatientPayload;
  patientAddress: PatientAddressPayload;  // Required
}

PatientPayload

{
  firstName: string;
  lastName: string;
  countryCode: string;
  phoneNumber: string;
  email?: string;
  age?: number;
  gender?: "MALE" | "FEMALE" | "OTHER";
}

PatientAddressPayload

{
  addressLine1?: string;
  city?: string;
  state?: string;
  country?: string;
  zipcode?: string;
  landmark?: string;
}

React Integration

Pre-built appointment calendar component for React applications.

import { AppointmentCalender } from 'medos-sdk';

function BookingPage() {
  return <AppointmentCalender />;
}

The component automatically uses the initialized MedosClient instance.

API Reference

MedosClient

init(config)

Initialize the SDK with an API key (server-side).

Parameters:

• config.apiKey (string, required) - Your Medos API key
• config.baseURL (string, optional) - API base URL. Defaults to dev environment

Returns: Promise<void>

initWithSession(config)

Initialize the SDK with a session token (client-side).

Parameters:

• config.sessionToken (string, required) - Session token
• config.baseURL (string, optional) - API base URL. Defaults to dev environment

Returns: Promise<void>

fetchAllAddressesAndDoctors()

Fetch all clinic addresses and their associated doctors.

Returns: Promise<AddressesResponse>

Response Type:

{
  totalAddresses?: number;
  totalDoctors?: number;
  workspaceId?: number | string;
  addresses: Array<{
    id: string;
    completeAddress?: string;
    addressLine1?: string;
    city?: string;
    state?: string;
    country?: string;
    zipcode?: string;
    doctors?: Array<{
      id: string;
      name: string;
      email?: string;
      specialty?: string;
    }>;
  }>;
}

fetchAppointments(workspaceId, addressId, doctorId, appointmentDate)

Fetch available appointment slots for a specific doctor.

Parameters:

• workspaceId (string | number) - Workspace identifier
• addressId (string | number) - Address identifier
• doctorId (string | number) - Doctor identifier
• appointmentDate (string) - Date in YYYY-MM-DD format

Returns: Promise<Slot[]>

Response Type:

Array<{
  start: string;  // ISO datetime format
  end: string;    // ISO datetime format
  id?: string;
}>

sendPhoneVerificationOtp(payload)

Send OTP to a phone number for verification.

Parameters:

• payload.countryCode (string) - Country code with + prefix (e.g., "+1")
• payload.phoneNumber (string) - Phone number without country code

Returns: Promise<any>

verifyPhoneVerificationOtp(payload)

Verify OTP for a phone number.

Parameters:

• payload.countryCode (string) - Country code with + prefix
• payload.phoneNumber (string) - Phone number without country code
• payload.otp (string) - OTP code received

Returns: Promise<any>

AppointmentService

createAppointment(payload)

Create a new appointment booking.

Parameters:

• payload (BookAppointmentPayload) - Appointment details

Returns: Promise<any>

Error Handling

All SDK methods return Promises and should be wrapped in try-catch blocks.

try {
  await MedosClient.init({ apiKey: 'your-api-key' });
  const addresses = await MedosClient.fetchAllAddressesAndDoctors();
} catch (error) {
  console.error('Failed to fetch addresses:', error.message);
}

Requirements

• Node.js: v14 or higher
• Browsers: Modern browsers with ES6+ support
• React: v19 or higher (for React components)
• TypeScript: v5 or higher (optional)

License

UNLICENSED

Support

For bug reports and feature requests, please visit our GitHub Issues.

Author

Pooranjoy Bhattacharya

Built for healthcare providers worldwide.