The FHIR R4 PractitionerRole resource defines the role, specialty, location, and organizational affiliation of a practitioner. It is used to represent a practitioner's position within an organization and to associate them with locations where they provide care. Health Gorilla supports reading, creating, updating, and deleting PractitionerRole records.

Use Cases

Associate a provider with their clinic, department, or healthcare organization
Identify specialties and available service locations for a practitioner
Filter practitioners by role, specialty, or managing organization

Base URLs

Production: https://api.healthgorilla.com/fhir/R4/PractitionerRole
Sandbox: https://sandbox.healthgorilla.com/fhir/R4/PractitionerRole

Authentication

All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.

Required Scopes

practitionerrole.read for GET
practitionerrole.write for POST, PUT, DELETE

For more information, go to: OAuth 2.0 Authentication.

Supported Methods

PractitionerRole Methods

Method	Operation	Description
`GET`	Read PractitionerRole	Retrieves a specific PractitionerRole record by its FHIR ID.
`GET`	Search PractitionerRole	Searches for PractitionerRole records using supported parameters.
`POST`	Create PractitionerRole	Submits a new PractitionerRole record to the Health Gorilla FHIR server.
`PUT`	Update PractitionerRole	Updates an existing PractitionerRole record by full resource replacement.

Frequently Used Search Parameters

Parameter	Description	FHIR Value Set / Example Values	FHIR Data Type	Required
`practitioner`	Filters by the referenced Practitioner ID	`Practitioner/{id}`	`Reference`	No
`organization`	Filters by affiliated Organization ID	`Organization/{id}`	`Reference`	No
`location`	Filters by associated Location ID	`Location/{id}`	`Reference`	No
`specialty`	Filters by the practitioner’s specialty	`Specialty` (`cardiology`)	`token`	No
`role`	Filters by the practitioner's functional role	`PractitionerRoleCode` (`nurse`, `doctor`)	`token`	No
`_id`	Filters by the PractitionerRole FHIR ID	`PractitionerRole/{id}`	`token`	No

Commonly Returned Resource Attributes

Attribute	Description	Example Values	FHIR Data Type	Required
`id`	Unique FHIR ID for the PractitionerRole	`prrole-123456`	`id`	Yes
`practitioner`	Reference to the individual practitioner	`Practitioner/{id}`	`Reference(Practitioner)`	Yes
`organization`	Organization where the role is performed	`Organization/{id}`	`Reference(Organization)`	No
`location`	Locations where the practitioner provides services	`Location/{id}`	`Reference[]`	No
`code`	Functional role within the organization	`doctor`	`CodeableConcept[]`	No
`specialty`	Practitioner’s area of clinical focus	`cardiology`	`CodeableConcept[]`	No
`telecom`	Contact details for scheduling or inquiries	Phone, email, fax	`ContactPoint[]`	No
`period`	Time period when the role is/was active	`2022-01-01 to 2023-12-31`	`Period`	No
`active`	Whether the practitioner currently holds this role	`true`	`boolean`	No
`endpoint`	References to scheduling, messaging, or other service endpoints	`Endpoint/{id}`	`Reference[]`	No

Webhooks

PractitionerRole records are not directly webhook-triggered, but they may appear as references in payloads for events such as Encounter, Appointment, or MedicationRequest.

For more information, go to: Webhooks & Polling.

Error Handling

All PractitionerRole operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses.
For more information, go to: Error Handling.

Additional Resources

HL7 FHIR PractitionerRole