Skip to main content
Use this endpoint to create a practitioner role that links a practitioner to an organization, location, and clinical role. A practitioner role maps to a FHIR R4 PractitionerRole resource and defines how a practitioner operates within your system — their role type, availability, and contact information for that context. Both practitionerId and role are required.

​
Request

POST /v1/practitioner-roles
​
practitionerId
string
required
The ID of the practitioner this role belongs to.
​
role
string
required
Role code describing the practitioner’s function. One of doctor, nurse, pharmacist, admin, or consultant. Maximum 100 characters.
​
organizationName
string
Name of the organization or practice this role is associated with. Maximum 200 characters.
​
specialty
string[]
List of specialties applicable to this role.
​
locationName
string
Name of the location where this role is performed, e.g. Main Campus or Telehealth. Maximum 200 characters.
​
phone
string
Contact phone number for this role.
​
email
string
Contact email address for this role.
​
availableDays
string[]
Days of the week when the practitioner is available in this role. Valid values: mon, tue, wed, thu, fri, sat, sun.
​
availableStartTime
string
Start of the available time window in HH:mm format (24-hour), e.g. 08:00.
​
availableEndTime
string
End of the available time window in HH:mm format (24-hour), e.g. 17:00.

​
Response

Returns 201 Created with the newly created practitioner role object.
​
data.id
string
Unique identifier for the practitioner role.
​
data.practitionerId
string
ID of the associated practitioner.
​
data.role
string
Role code.
​
data.organizationName
string
Organization name.
​
data.specialty
string[]
Specialties for this role.
​
data.locationName
string
Location name.
​
data.availableDays
string[]
Days of availability.
​
data.availableStartTime
string
Availability start time.
​
data.availableEndTime
string
Availability end time.
​
data.createdAt
string
ISO 8601 timestamp when the record was created.
​
meta
object
Request metadata including requestId, timestamp, status, and rate limit fields.
curl -X POST https://api.clinikehr.com/v1/practitioner-roles \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "practitionerId": "prc_03kz6m1o4p5r7s9t0u",
    "role": "doctor",
    "organizationName": "Springfield Cardiology Group",
    "specialty": ["Cardiology", "Interventional Cardiology"],
    "locationName": "Main Campus",
    "email": "[email protected]",
    "availableDays": ["mon", "tue", "wed", "thu", "fri"],
    "availableStartTime": "08:00",
    "availableEndTime": "17:00"
  }'
Response
{
  "data": {
    "id": "prr_04la7n2p5q6s8t0u1v",
    "practitionerId": "prc_03kz6m1o4p5r7s9t0u",
    "role": "doctor",
    "organizationName": "Springfield Cardiology Group",
    "specialty": ["Cardiology", "Interventional Cardiology"],
    "locationName": "Main Campus",
    "phone": null,
    "email": "[email protected]",
    "availableDays": ["mon", "tue", "wed", "thu", "fri"],
    "availableStartTime": "08:00",
    "availableEndTime": "17:00",
    "createdAt": "2025-01-15T09:45:00.000Z"
  },
  "meta": {
    "requestId": "req_w8p3i7b0",
    "timestamp": "2025-01-15T09:45:00.000Z",
    "status": 201,
    "rateLimitTotal": 500,
    "rateLimitRemaining": 489,
    "rateLimitReset": 3420
  }
}