Skip to main content

Practitioner Roles

PractitionerRole defines the role a practitioner plays at a specific organization or location. A single practitioner can have multiple roles — cardiologist at one hospital, consultant at another clinic.

Create a Practitioner Role

const { data: role } = await clinik.practitionerRoles.create({
  practitionerId: 'prac_abc123',
  organizationName: 'Austin Heart Clinic',
  role: 'doctor',
  specialty: ['Cardiology', 'Interventional Cardiology'],
  locationName: 'Main Campus - Building A',
  phone: '+1-555-0100',
  email: '[email protected]',
  period: { start: '2024-01-01' },
  availableTime: [
    {
      daysOfWeek: ['mon', 'tue', 'wed', 'thu', 'fri'],
      availableStartTime: '08:00:00',
      availableEndTime: '17:00:00',
    },
  ],
  notAvailable: [
    { description: 'Annual leave', during: { start: '2025-08-01', end: '2025-08-15' } },
  ],
  availabilityExceptions: 'Closed on public holidays',
});

Multiple Availability Schedules

A practitioner can have different hours on different days:
await clinik.practitionerRoles.create({
  practitionerId: 'prac_abc123',
  organizationName: "St. David's Medical Center",
  role: 'consultant',
  specialty: ['Cardiology'],
  availableTime: [
    {
      daysOfWeek: ['tue', 'thu'],
      availableStartTime: '13:00:00',
      availableEndTime: '17:00:00',
    },
    {
      daysOfWeek: ['sat'],
      availableStartTime: '09:00:00',
      availableEndTime: '12:00:00',
    },
  ],
});

Unavailability Periods

Mark periods when the practitioner is not available:
await clinik.practitionerRoles.update('role_xyz789', {
  notAvailable: [
    { description: 'Medical conference', during: { start: '2025-06-10', end: '2025-06-14' } },
    { description: 'Personal leave', during: { start: '2025-07-01', end: '2025-07-05' } },
  ],
  availabilityExceptions: 'May be available for emergencies during leave periods',
});

Update Availability

await clinik.practitionerRoles.update('role_xyz789', {
  availableDays: ['mon', 'wed', 'fri'],
  availableStartTime: '09:00',
  availableEndTime: '16:00',
});

Deactivate a Role

await clinik.practitionerRoles.update('role_xyz789', {
  active: false,
});

Search Roles

const { data } = await clinik.practitionerRoles.search({
  count: 50,
});

Practitioner vs PractitionerRole

ResourcePurpose
PractitionerThe person (name, NPI, qualifications)
PractitionerRoleWhere/when they practice (org, schedule, specialty in context)
A practitioner is created once. Roles are created for each organization/location they work at.