The FHIR R4 Practitioner resource describes an individual involved in the delivery of healthcare services, such as a physician, nurse, therapist, or pharmacist. This resource captures demographics, credentials, contact details, and affiliations with healthcare organizations.
Use Cases
- Identify the clinician responsible for a medication, diagnosis, or encounter
- Display provider contact details for care coordination
- Associate a practitioner with their roles, specialties, and organizations
Base URLs
- Production: https://api.healthgorilla.com/fhir/R4/Practitioner
- Sandbox: https://sandbox.healthgorilla.com/fhir/R4/Practitioner
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.
Required Scope: practitioner.read for GET
For more information, go to: OAuth 2.0 Authentication.
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read Practitioner | Retrieves a specific Practitioner record by its FHIR ID. |
GET | Search Practitioner | Searches for Practitioner records using supported parameters. |
Search Parameters
Practitioner supports three search forms, and a request must use one of them:
identifieron its own.- A directory search on
rolenarrowed bynearandnear-distancetogether. - A directory search on
rolenarrowed by address.
A name search on its own isn't supported. Pair name with role and either a proximity or an address filter.
| Parameter | Required | Description |
|---|---|---|
identifier | Required in the identifier search | Returns the practitioner carrying the given identifier. |
role | Required in both directory searches | The practitioner role to return. |
near | Required with near-distance | The city or postal code to search around. |
near-distance | Required with near | The distance to search within. |
name | No | Filters on the practitioner name. |
specialty | No | Filters on the practitioner specialty. |
address-state | No | Filters on the state in the practitioner address. |
address-city | No | Filters on the city in the practitioner address. |
address-postalcode | No | Filters on the postal code in the practitioner address. |
_offset | No | Skips the given number of results. |
_count | No | Limits the number of results returned per page. |
The search also accepts _revinclude=PractitionerRole:practitioner, which returns the roles held by the practitioners in the results.
Use specialty. The misspelling speciality is rejected with an error naming the correct parameter.
Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type | Required |
|---|---|---|---|---|
id | Unique FHIR ID for the practitioner | pract-456789 | id | Yes |
identifier | National or state license identifiers | NPI: 1234567890 | Identifier[] | No |
name | Full name of the practitioner | Jane Smith, MD | HumanName[] | Yes |
telecom | Contact information | 555-555-5555, [email protected] | ContactPoint[] | No |
address | Work address | 123 Wellness Way, Sunnyvale, CA | Address[] | No |
gender | Gender identity | female | code | No |
birthDate | Date of birth | 1975-05-10 | date | No |
qualification | Degrees, board certifications, or licenses | MD, Board Certified Internal Medicine | Practitioner.Qualification[] | No |
communication | Languages spoken by the practitioner | en, es, zh | CodeableConcept[] | No |
Webhooks
Practitioner resources are not typically the direct subject of webhook notifications, but they are frequently referenced in payloads for clinical events such as MedicationRequest, Encounter, and Condition.
For more information, go to: Webhooks & Polling.
Error Handling
All Practitioner operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses.
For more information, go to: Error Handling.