> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinikapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Practitioner Roles

> SDK reference for practitioner role operations.

# clinik.practitionerRoles

PractitionerRole defines the role a practitioner plays at a specific organization or location — their specialty, availability, and contact info in that context.

A single practitioner can have multiple roles (e.g. cardiologist at Hospital A, consultant at Clinic B).

## create

```ts theme={null}
const { data, meta } = await clinik.practitionerRoles.create(request: PractitionerRoleCreateRequest): Promise<ApiResponse<PractitionerRole>>
```

| Field                    | Type       | Required | Description                                                    |
| ------------------------ | ---------- | -------- | -------------------------------------------------------------- |
| `practitionerId`         | `string`   | Yes      | Reference to the Practitioner                                  |
| `organizationName`       | `string`   | No       | Organization name                                              |
| `role`                   | `string`   | Yes      | Role code (e.g. "doctor", "nurse", "admin")                    |
| `specialty`              | `string[]` | No       | Specialties in this role                                       |
| `locationName`           | `string`   | No       | Location/facility name                                         |
| `phone`                  | `string`   | No       | Contact phone for this role                                    |
| `email`                  | `string`   | No       | Contact email for this role                                    |
| `period`                 | `object`   | No       | Period during which the role is valid (`{ start, end }`)       |
| `availableTime`          | `Array`    | No       | Multiple availability schedules (see below)                    |
| `notAvailable`           | `Array`    | No       | Periods when the practitioner is not available                 |
| `availabilityExceptions` | `string`   | No       | Free-text description of availability exceptions               |
| `availableDays`          | `string[]` | No       | Legacy: days available (mon-sun). Use `availableTime` instead. |
| `availableStartTime`     | `string`   | No       | Legacy: start time (HH:mm:ss). Use `availableTime` instead.    |
| `availableEndTime`       | `string`   | No       | Legacy: end time (HH:mm:ss). Use `availableTime` instead.      |

### Available Time

Each entry in `availableTime` supports:

| Field                | Type       | Description                             |
| -------------------- | ---------- | --------------------------------------- |
| `daysOfWeek`         | `string[]` | Days: mon, tue, wed, thu, fri, sat, sun |
| `allDay`             | `boolean`  | Whether available all day (24h)         |
| `availableStartTime` | `string`   | Start time (HH:mm:ss)                   |
| `availableEndTime`   | `string`   | End time (HH:mm:ss)                     |

### Not Available

Each entry in `notAvailable` supports:

| Field         | Type     | Required | Description                               |
| ------------- | -------- | -------- | ----------------------------------------- |
| `description` | `string` | Yes      | Reason (e.g. "On vacation", "Conference") |
| `during`      | `object` | No       | Period: `{ start, end }`                  |

### Example

```ts theme={null}
const { data } = 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: 'dr.chen@austinheart.com',
  period: { start: '2024-01-01' },
  availableTime: [
    {
      daysOfWeek: ['mon', 'tue', 'wed', 'thu', 'fri'],
      availableStartTime: '08:00:00',
      availableEndTime: '17:00:00',
    },
    {
      daysOfWeek: ['sat'],
      availableStartTime: '09:00:00',
      availableEndTime: '12:00:00',
    },
  ],
  notAvailable: [
    {
      description: 'Annual medical conference',
      during: { start: '2025-03-10', end: '2025-03-14' },
    },
  ],
  availabilityExceptions: 'Closed on public holidays',
});
```

## read

```ts theme={null}
const { data, meta } = await clinik.practitionerRoles.read(id: string): Promise<ApiResponse<PractitionerRole>>
```

## update

```ts theme={null}
const { data, meta } = await clinik.practitionerRoles.update(id: string, request: PractitionerRoleUpdateRequest): Promise<ApiResponse<PractitionerRole>>
```

```ts theme={null}
await clinik.practitionerRoles.update('role_xyz789', {
  availableDays: ['mon', 'wed', 'fri'],
  availableStartTime: '09:00',
  availableEndTime: '16:00',
  active: false, // deactivate this role
});
```

## delete

```ts theme={null}
const { data, meta } = await clinik.practitionerRoles.delete(id: string): Promise<ApiResponse<void>>
```

## search

```ts theme={null}
const { data, meta } = await clinik.practitionerRoles.search(params?: ResourceSearchParams): Promise<ApiResponse<PaginatedResponse<PractitionerRole>>>
```

| Parameter   | Type     | Description                        |
| ----------- | -------- | ---------------------------------- |
| `patientId` | `string` | Not applicable — use other filters |
| `status`    | `string` | Filter by active status            |
| `count`     | `number` | Results per page (max: 100)        |
| `cursor`    | `string` | Pagination cursor                  |