PractitionerRole

Overview

The PractitionerRole resource represents specific roles, locations, specialties, and services that a practitioner performs at an organization during a particular time period. This resource links practitioners to their organizational contexts and capabilities.

Important: Always validate PractitionerRole resource support and available operations by retrieving the current CapabilityStatement from /metadata before implementing integrations.

Resource Schema

The PractitionerRole resource follows the HL7 FHIR R4 PractitionerRole specification.

Key elements include:

identifier - Business identifiers for the role
active - Whether this role is in active use
period - Period during which practitioner is authorized in this role
practitioner - Practitioner that is able to provide services
organization - Organization where roles are available
code - Roles which this practitioner is authorized to perform
specialty - Specific specialty of the practitioner
location - Location(s) where practitioner provides care
healthcareService - Healthcare service(s) provided
telecom - Contact details for this role
availableTime - Times the practitioner is available
notAvailable - Not available during this time
availabilityExceptions - Description of availability exceptions
endpoint - Technical endpoints for this role

Example PractitionerRole Resource

{
  "resourceType": "PractitionerRole",
  "id": "12345",
  "identifier": [{
    "use": "official",
    "system": "http://hospital.example.org/practitioner-roles",
    "value": "ROLE-2024-001"
  }],
  "active": true,
  "period": {
    "start": "2024-01-01",
    "end": "2024-12-31"
  },
  "practitioner": {
    "reference": "Practitioner/67890",
    "display": "Dr. John Smith"
  },
  "organization": {
    "reference": "Organization/hospital-123",
    "display": "Medical Center Hospital"
  },
  "code": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/practitioner-role",
      "code": "doctor",
      "display": "Doctor"
    }]
  }],
  "specialty": [{
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "394814009",
      "display": "General practice"
    }]
  }],
  "location": [{
    "reference": "Location/clinic-456",
    "display": "Main Clinic"
  }],
  "telecom": [{
    "system": "phone",
    "value": "+1-555-123-4567",
    "use": "work"
  }, {
    "system": "email",
    "value": "john.smith@hospital.example.org",
    "use": "work"
  }],
  "availableTime": [{
    "daysOfWeek": ["mon", "tue", "wed", "thu", "fri"],
    "availableStartTime": "08:00:00",
    "availableEndTime": "17:00:00"
  }]
}

Supported Profiles

This API supports the following FHIR profiles:

HL7 FHIR R4 PractitionerRole

Operations

The General Purpose FHIR R4 PractitionerRole resource supports the following standard operations. However, support varies by the targeted CareRecord or solution.

CareRecord / Solution	Create	Read	Update	Search
GEHRIMED	-	-	-	-
myAvatar	-	-	-	-
myEvolv	-	-	-	-
myUnity	-	-	-	-
Referral Manager	-	-	-	-

Search

info

Not all Netsmart solutions support PractitionerRole search. See supported operations table above and consult your target solution's documentation for more information.

This resource supports a combination of standard and custom search parameters in addition to the common parameters.

Standard Parameters

Name	Type	Description
active	token	Whether this practitioner role record is in active use
date	date	The period during which the practitioner is authorized to perform in these role(s)
email	token	A value in an email contact
location	reference	One of the locations at which this practitioner provides care
organization	reference	The identity of the organization the practitioner represents/acts on behalf of
phone	token	A value in a phone contact
practitioner	reference	Practitioner that is able to provide the defined services for the organization
role	token	The practitioner can perform this role at/for the organization
speciality	token	The practitioner has this speciality at an organization

Search Examples

The POST method is recommended as it keeps health information out of the URL.

Production
Preview

Search Practitioner Role Resource by Date
curl -X POST https://fhir.netsmartcloud.com/v4/PractitionerRole/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "date=ge2024-08-01&date=le2024-08-27" \
    

Search Practitioner Role Resource by Date
curl -X POST https://fhirtest.netsmartcloud.com/v4/PractitionerRole/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "date=ge2024-08-01&date=le2024-08-27" \
    

Error Handling

For information about error responses when working with PractitionerRole resources, see Common Errors.

Common PractitionerRole-related errors include:

Invalid practitioner or organization references
Unsupported role or specialty codes
Malformed period dates or availability times
Invalid location or healthcare service references

Integration Patterns

Provider Directory

Find practitioners by role and specialty:

# Search by specialty
curl -X GET "https://fhir.netsmartcloud.com/v4/PractitionerRole?specialty=394814009" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Organizational Workflows

Find roles within an organization:

# Search by organization
curl -X GET "https://fhir.netsmartcloud.com/v4/PractitionerRole?organization=Organization/hospital-123" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Location-Based Services

Find practitioners at specific locations:

# Search by location
curl -X GET "https://fhir.netsmartcloud.com/v4/PractitionerRole?location=Location/clinic-456" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Scheduling Integration

Find active practitioner roles:

# Search active roles by date range
curl -X GET "https://fhir.netsmartcloud.com/v4/PractitionerRole?active=true&date=ge2024-01-01" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Relationships to Other Resources

The PractitionerRole resource serves as a bridge connecting practitioners to organizational contexts:

Practitioner - The healthcare professional performing the role
Organization - The organization where the role is performed
Location - Physical locations where services are provided
Encounter - Clinical encounters involving practitioners in specific roles
MedicationRequest - Prescriptions written by practitioners in their roles
Procedure - Procedures performed by practitioners in their roles
Immunization - Vaccinations administered by practitioners in their roles

Support

For questions about PractitionerRole resource implementation or provider network management, contact Netsmart support through your designated support channels.

Overview​

Resource Schema​

Example PractitionerRole Resource​

Supported Profiles​

Operations​

Search​

Standard Parameters​

Search Examples​

Error Handling​

Integration Patterns​

Provider Directory​

Organizational Workflows​

Location-Based Services​

Scheduling Integration​

Relationships to Other Resources​

Support​