Skip to main content
Use this endpoint to search for practitioner roles within your tenant. You can filter by practitioner, specialty, or status to find relevant role assignments. Results are paginated — use count and cursor to page through large result sets.

​
Request

GET https://api.clinikapi.com/v1/practitioner-roles

​
Headers

​
x-api-key
string
required
Your ClinikAPI secret key (clk_live_* or clk_test_*).

​
Query Parameters

​
practitionerId
string
Filter roles by practitioner ID. Returns all roles held by the specified practitioner.
​
specialty
string
Filter by specialty display name or code. Partial, case-insensitive match on the specialty.display field.
​
status
string
Filter by role status. One of: active, inactive.
​
count
integer
Number of results per page. Default: 20. Maximum: 100.
​
cursor
string
Opaque pagination cursor from the previous response’s data.cursor field.

​
Response

Returns 200 OK with a paginated list of practitioner role records.
​
data.data
array
Array of practitioner role objects matching the search criteria.
​
data.total
integer
Total number of roles matching the search, across all pages.
​
data.cursor
string
Cursor to pass in the next request to retrieve the following page. null when there are no more results.
​
data.hasMore
boolean
true if there are additional pages of results.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Examples

​
curl — filter by practitioner

curl "https://api.clinikapi.com/v1/practitioner-roles?practitionerId=prac_abc123&status=active" \
  -H "x-api-key: clk_live_abc123"

​
curl — filter by specialty

curl "https://api.clinikapi.com/v1/practitioner-roles?specialty=Cardiology&count=10" \
  -H "x-api-key: clk_live_abc123"

​
Paginating through results

# First page
curl "https://api.clinikapi.com/v1/practitioner-roles?count=20" \
  -H "x-api-key: clk_live_abc123"

# Next page using cursor from previous response
curl "https://api.clinikapi.com/v1/practitioner-roles?count=20&cursor=eyJpZCI6InByX2..." \
  -H "x-api-key: clk_live_abc123"

​
TypeScript SDK

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

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

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

console.log(results.data.total);   // e.g. 3
console.log(results.data.hasMore); // false

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