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.readfor GETpractitionerrole.writefor POST, PUT, DELETE
For more information, go to: OAuth 2.0 Authentication.
Supported 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. |
Search Parameters
Every search needs one anchor. Supply exactly one of identifier, practitioner, or organization. The location, role, specialty, activated, and email filters are only available alongside organization.
| Parameter | Required | Description |
|---|---|---|
identifier | One anchor required | Returns the role carrying the given identifier. |
practitioner | One anchor required | Returns the roles held by the given practitioner, as Practitioner/{id}. |
organization | One anchor required | Returns the roles at the given organization, as Organization/{id}. |
location | No, with organization | Returns the roles at the given location. |
role | No, with organization | Filters on the role. |
specialty | No, with organization | Filters on the specialty. |
activated | No, with organization | Filters on whether the role is activated. |
email | No, with organization | Filters on the email address on the role. |
_tag | No | Filters on meta.tag. |
_security | No | Filters on meta.security. |
The search also accepts _include=PractitionerRole:practitioner, _include=PractitionerRole:location, and _include=PractitionerRole:organization to return referenced resources.
Use specialty. The misspelling speciality is rejected with an error naming the correct parameter.
Searching by Organization and NPI
You can find a practitioner within a tenant by passing the organization and identifier parameters together in a single PractitionerRole search. The identifier parameter carries the practitioner's NPI in system|value form, and organization scopes the search to one tenant. Health Gorilla returns only the practitioner roles that match both parameters, so a single call replaces querying by one parameter and filtering the results yourself. You can still search by identifier or organization alone: combining them narrows the results to practitioners that match both.
Example
GET /fhir/R4/PractitionerRole?identifier=http://hl7.org/fhir/sid/us-npi|1234567893&organization=t-<tenant-id>The response is a Bundle of type searchset, which lists the matching resources and reports how many matched in total. When a practitioner holds more than one role at the organization, the Bundle contains one entry per role, so read total and iterate the entry array rather than assuming a single result. When no practitioner matches both parameters, the Bundle is empty with total of 0.
The identifier value must include the NPI namespace, http://hl7.org/fhir/sid/us-npi. An identifier without a namespace returns 400 Bad Request, and an unsupported namespace also returns 400. You can search only within your own tenant: a request that scopes organization to a tenant other than your own returns 405 Method Not Allowed, which here signals a cross-tenant scope restriction rather than an unsupported HTTP method.
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.