Skip to main content
The clinik.practitionerRoles namespace manages FHIR PractitionerRole resources — the contextual assignments that link a practitioner to a specific organization, location, and specialty. A single practitioner can hold multiple roles: for example, a cardiologist at one hospital and a part-time consultant at another clinic.
You must create a Practitioner before you can create a PractitionerRole. The practitionerId field references the practitioner’s ID from clinik.practitioners.create.

​
create

Create a new PractitionerRole. Both practitionerId and role are required. 
const { data, meta } = await clinik.practitionerRoles.create(request: PractitionerRoleCreateRequest): Promise<ApiResponse<PractitionerRole>>
​
practitionerId
string
required
ID of the practitioner this role belongs to (e.g. prac_abc123).
​
role
string
required
Role code describing the practitioner’s function. Common values: doctor, nurse, consultant, admin.
​
organizationId
string
Reference ID of the organization where this role is performed.
​
locationId
string
Reference ID of the location or facility associated with this role.
​
specialty
object
Medical specialty in the context of this role. Accepts code and display fields.
​
status
'active' | 'inactive'
Role status. Defaults to active.
​
period
object
Date range during which this role is active. Accepts start and optional end in YYYY-MM-DD format.

​
Example — full-time cardiologist

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

const { data } = await clinik.practitionerRoles.create({
  practitionerId: 'prac_abc123',
  role: 'doctor',
  organizationId: 'org_heart001',
  locationId: 'loc_main001',
  specialty: {
    code: '394579002',
    display: 'Cardiology',
  },
  status: 'active',
  period: {
    start: '2024-01-01',
  },
});

console.log(data.id); // pr_abc123

​
Example — part-time consultant

const { data } = await clinik.practitionerRoles.create({
  practitionerId: 'prac_abc123',
  role: 'consultant',
  organizationId: 'org_clinic002',
  specialty: {
    display: 'Interventional Cardiology',
  },
  period: {
    start: '2024-06-01',
    end: '2025-05-31',
  },
});

​
read

Fetch a single practitioner role by ID. 
const { data, meta } = await clinik.practitionerRoles.read(id: string): Promise<ApiResponse<PractitionerRole>>
​
id
string
required
The practitioner role ID (e.g. pr_abc123).

​
Example

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

const { data } = await clinik.practitionerRoles.read('pr_abc123');

console.log(data.role);              // "doctor"
console.log(data.specialty.display); // "Cardiology"
console.log(data.status);            // "active"

​
update

Partially update a practitioner role. Only the fields you include are changed. 
const { data, meta } = await clinik.practitionerRoles.update(id: string, request: PractitionerRoleUpdateRequest): Promise<ApiResponse<PractitionerRole>>
​
id
string
required
The practitioner role ID to update.
​
role
string
Updated role code.
​
organizationId
string
Updated organization reference.
​
locationId
string
Updated location reference.
​
specialty
object
Updated specialty object. Replaces the entire specialty.
​
status
'active' | 'inactive'
Updated role status.
​
period
object
Updated active date range. Replaces the entire period object.

​
Example — update specialty

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

await clinik.practitionerRoles.update('pr_abc123', {
  specialty: {
    code: '394819006',
    display: 'Interventional Cardiology',
  },
});

​
Example — deactivate a role

await clinik.practitionerRoles.update('pr_abc123', {
  status: 'inactive',
  period: {
    start: '2024-01-01',
    end: '2025-12-31',
  },
});
Prefer status: 'inactive' over deleting a role when you may need to reactivate it later or preserve the historical assignment for audit purposes.

​
delete

Permanently delete a practitioner role record. 
const { data, meta } = await clinik.practitionerRoles.delete(id: string): Promise<ApiResponse<void>>
​
id
string
required
The practitioner role ID to delete.

​
Example

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

await clinik.practitionerRoles.delete('pr_abc123');
// Resolves with no value on success
Search practitioner roles by practitioner, specialty, or status. 
const { data, meta } = await clinik.practitionerRoles.search(params?: PractitionerRoleSearchParams): Promise<ApiResponse<PaginatedResponse<PractitionerRole>>>
​
practitionerId
string
Filter roles by practitioner ID. Returns all roles held by the specified practitioner.
​
specialty
string
Filter by specialty display name or code. Case-insensitive partial match.
​
status
string
Filter by role status. One of: active, inactive.
​
count
number
Results per page. Maximum is 100.
​
cursor
string
Pagination cursor from a previous response.

​
Example — all active roles for a practitioner

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

const { data } = await clinik.practitionerRoles.search({
  practitionerId: 'prac_abc123',
  status: 'active',
});

console.log(`${data.total} active roles`);

for (const role of data.data) {
  console.log(role.role, role.specialty?.display, role.organizationId);
}

​
Example — all cardiologists

const { data } = await clinik.practitionerRoles.search({
  specialty: 'Cardiology',
  status: 'active',
  count: 50,
});

console.log('Active cardiologists in roles:', data.total);