Create a Clinical User
The PractitionerRole FHIR endpoint creates users and manages their universally unique identifiers (UUIDs). Two types of users can be created: clinical users, who deliver care, and non-clinical users, who handle administrative work.
Clinical users include providers as well as the nurses and staff who place orders on a provider's behalf. Only a provider has a National Provider Identifier (NPI). Non-clinical users, such as office managers and billing staff, don't have an NPI. Both types are created the same way, with the same attributes.
Each user is created with a PractitionerRole FHIR resource. Creating a clinical user has two parts:
- Retrieving the
PractitionerFHIR resource for the clinician - Creating the
PractitionerRoleFHIR resource
Note: The create_users scope is required when creating users through the PractitionerRole API.
PractitionerRole Attributes
| Attribute | Required | Notes |
|---|---|---|
resourceType | Yes | Always PractitionerRole. |
meta | Yes | Contains a required profile attribute and an optional tag attribute that controls email invitations and notifications for new users. |
active | Yes | Always set to true when creating new users. |
practitioner | Yes | Contains a reference to an internal Practitioner resource that describes the user to be created. |
code | Yes | Contains the required administrative-role and practitioner-role. |
location | No | Associates the clinical user with specific tenant locations. When omitted, the clinical user is associated with all tenant locations. |
organization | No | Used when creating a user in a different tenant. To create a tenant, go to Creating a Tenant. |
Internal Practitioner Attributes
| Attribute | Required | Notes |
|---|---|---|
resourceType | Yes | Always Practitioner. |
id | Yes | The ID of the resource, referenced in the PractitionerRole.practitioner attribute. |
meta | Yes | Contains a required profile attribute. |
identifier | Yes | Contains a required attribute representing the provider's NPI. Can also contain an optional attribute representing a lab account number, and an optional attribute that assigns a UUID to the clinical user for Health Gorilla's Single Sign-On (SSO) option. |
name | Yes | Contains the clinical user's name. |
telecom | No | Adds the clinical user's email to the account. |
extension | Yes | Passes a required username and an optional password for the account. |
Retrieve the Practitioner Resource by NPI
When you create a provider, the person's information must match Health Gorilla's NPI directory of United States providers. You retrieve the Practitioner FHIR resource by querying the Practitioner FHIR endpoint with the provider's NPI. The provider's name attribute is used to create the Practitioner resource contained in the PractitionerRole resource and must match exactly.
{portalURL}/fhir/R4/Practitioner?identifier=http://hl7.org/fhir/sid/us-npi%7C<PROVIDER_NPI>{
"resourceType": "Bundle",
"id": "94f3dead-91a3-464d-8886-03fe7738dca6",
"meta": {
"lastUpdated": "2022-12-20T16:00:32.289+00:00",
"profile": [
"https://healthgorilla.com/fhir/StructureDefinition/hg-stateless-bundle"
]
},
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://sandbox.healthgorilla.com/fhir/R4/Practitioner?identifier=http://hl7.org/fhir/sid/us-npi%7C123456789"
}
],
"entry": [
{
"fullUrl": "https://sandbox.healthgorilla.com/fhir/R4/Practitioner/c91b6b63c0b2599e7850be7d",
"resource": {
"resourceType": "Practitioner",
"id": "c91b6b63c0b2599e7850be7f",
"meta": {
"versionId": "1667963849444",
"lastUpdated": "2022-11-09T03:17:29.444+00:00",
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner",
"https://healthgorilla.com/fhir/StructureDefinition/hg-practitioner"
]
},
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Joe Gorilla, PA, PA</div>"
},
"identifier": [
{
"system": "https://www.healthgorilla.com",
"value": "c91b6b63c0b2599e7850be7f"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "NPI",
"display": "National provider identifier"
}
],
"text": "National provider identifier"
},
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "123456789"
}
],
"active": true,
"name": [
{
"use": "official",
"text": "Joe Gorilla, PA, PA",
"family": "Gorilla",
"given": [
"Joe"
],
"suffix": [
"PA"
]
}
],
"address": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/geolocation",
"extension": [
{
"url": "latitude",
"valueDecimal": 36.888671
},
{
"url": "longitude",
"valueDecimal": -95.803761
}
]
}
],
"use": "work",
"text": "N/A, Lumberton, TX 95050",
"line": [
"N/A"
],
"city": "Lumberton",
"state": "TX",
"postalCode": "95050",
"country": "USA"
},
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/geolocation",
"extension": [
{
"url": "latitude",
"valueDecimal": 36.0798826
},
{
"url": "longitude",
"valueDecimal": -95.4172549
}
]
}
],
"use": "work",
"text": "1572 Jungle, Rain Forest, TX 77706",
"line": [
"1572 Jungle"
],
"city": "Rain Forest",
"state": "TX",
"postalCode": "77706"
}
]
},
"search": {
"mode": "match"
}
}
]
}Create the PractitionerRole Resource
The PractitionerRole resource is what you build and send, containing the Practitioner resource you retrieved. Its other attributes carry the rest of the account information.
Email Invitations and Notifications
A new account is created with two things on: the email invitation asking the user to validate the account, and the email notifications set for it. Either can be turned off by adding an entry to the optional PractitionerRole.meta.tag array, with system set to https://www.healthgorilla.com and code set to the matching value. Omitting the tag array keeps both on.
code Value | Effect |
|---|---|
VERIFIED | The email address and mobile phone are treated as already verified, so no validation invitation is sent |
NO_SUBSCRIPTIONS | The account is created with no email notification subscriptions |
"tag":[
{
"system":"https://www.healthgorilla.com",
"code":"VERIFIED"
},
{
"system":"https://www.healthgorilla.com",
"code":"NO_SUBSCRIPTIONS"
}
]Administrative and Practitioner Roles
The PractitionerRole.code array sets the administrative-role and practitioner-role for the user. This attribute is required for user creation.
"code":[
{
"coding":[
{
"system":"https://www.healthgorilla.com/administrative-role",
"code":"provider",
"display":"provider"
},
{
"system":"http://hl7.org/fhir/practitioner-role",
"code":"doctor",
"display":"Doctor"
}
]
}
],Provider NPI
The internal Practitioner resource uses the Practitioner.identifier array to set the NPI for the provider. This field is required when creating a clinical user.
"contained": [
{
"resourceType": "Practitioner",
......
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "NPI",
"display": "National provider identifier"
}
],
"text": "National provider identifier"
},
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "<NPI NUMBER>"
}
]
}
]Lab Account Number
The internal Practitioner resource uses an attribute in the Practitioner.identifier array to set the lab account numbers for the provider. The field is optional to the request, but a provider without a lab account number cannot be selected as the ordering provider for that laboratory.
For more information about how the accounts are held and what users see when one is missing, go to Lab Ordering Tenant Setup.
"contained": [
{
"resourceType": "Practitioner",
......
"identifier": [
{
"type":{
"coding":[
{
"system":"http://terminology.hl7.org/CodeSystem/v2-0203",
"code":"AN",
"display":"Account number"
}
],
"text":"Account number"
},
"assigner":{
"reference":"Organization/f-<Lab Facility ID>"
},
"value":"<LAB ACCOUNT NUMBER>"
}
]
}
]Location-Specific Account Numbers
The PractitionerRole.location array associates the clinical user with specific locations in the tenant. This field is optional. When location is omitted, the clinical user is associated with every location in the tenant. Reference each location by its tenant location ID in the form Location/tl-<TENANT_ID>-<LOCATION_ID>.
A lab account number set on the provider, using the AN account-number identifier described under Lab Account Number, is bound to the referenced location instead of to every tenant location.
"location": [
{
"reference": "Location/tl-<TENANT_ID>-<LOCATION_ID>"
}
]User UUID for Single Sign-On
SSO works with the Health Gorilla iFrame. The internal Practitioner FHIR resource uses the Practitioner.identifier attribute to create the UUID. There is no required format for the unique identifier: any unique ID can be passed. The SSO facility associated with the user's tenant must be referenced in this attribute.
"contained": [
{
"resourceType": "Practitioner",
......
"identifier":[
{
"type":{
"coding":[
{
"system":"http://terminology.hl7.org/CodeSystem/v2-0203",
"code":"PRN",
"display":"Provider number"
}
],
"text":"Provider Number"
},
"value":"<USER'S UUID>",
"assigner":{
"reference":"Organization/f-<SSO FACILITY ID>"
}
}
],
}
]User's Real Name
The Practitioner.name attribute passes the user's real name to Health Gorilla. This value must match the name attribute from the Practitioner FHIR resource retrieved in Retrieve the Practitioner Resource by NPI. The user's real name is required to create a user account in Health Gorilla.
"contained": [
{
"resourceType": "Practitioner",
......
"name": [
{
"use": "official",
"text": "<FULL NAME>",
"family": "<LAST NAME>",
"given": [
"<FIRST NAME>"
]
}
],
}
]User's Email
The Practitioner.telecom attribute passes the user's email to the user account. This field is optional.
"contained": [
{
"resourceType": "Practitioner",
......
"telecom": [
{
"system": "email",
"value": "<USER EMAIL>",
"use": "work"
}
]
}
]Username and Password
Extensions carry the username and password. The username is required for account creation. A password is optional and is only required if the user logs into the Health Gorilla UI through the Health Gorilla login screen.
"contained": [
{
"resourceType": "Practitioner",
......
"extension": [
{
"url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-login",
"valueString": "<USERNAME>"
},
{
"url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-password",
"valueString": "<PASSWORD>"
}
]
}
]Target Tenant
Some clients manage multiple tenants, which requires creating users in more than one tenant. The organization attribute passes the target tenant's unique identifier to Health Gorilla.
"organization": {
"reference": "Organization/t-111e1e656869ac26d411820e"
},Full Example
The following example payload contains all available attributes. More examples are available at the Health Gorilla Git repo.
{
"resourceType":"PractitionerRole",
"meta":{
"profile":[
"https://healthgorilla.com/fhir/StructureDefinition/hg-user"
],
"tag":[
{
"system":"https://www.healthgorilla.com",
"code":"VERIFIED"
},
{
"system":"https://www.healthgorilla.com",
"code":"NO_SUBSCRIPTIONS"
}
]
},
"active":true,
"practitioner":{
"reference":"#pr"
},
"code":[
{
"coding":[
{
"system":"https://www.healthgorilla.com/administrative-role",
"code":"provider",
"display":"provider"
},
{
"system":"http://hl7.org/fhir/practitioner-role",
"code":"doctor",
"display":"Doctor"
}
]
}
],
"location":[
{
"reference":"Location/tl-<TENANT_ID>-<LOCATION_ID>"
}
],
"contained":[
{
"resourceType": "Practitioner",
"id": "pr",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner",
"https://healthgorilla.com/fhir/StructureDefinition/hg-practitioner"
]
},
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "NPI",
"display": "National provider identifier"
}
],
"text": "National provider identifier"
},
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "<NPI NUMBER>"
},
{
"type":{
"coding":[
{
"system":"http://terminology.hl7.org/CodeSystem/v2-0203",
"code":"AN",
"display":"Account number"
}
],
"text":"Account number"
},
"assigner":{
"reference":"Organization/f-<Lab Facility ID>"
},
"value":"<LAB ACCOUNT NUMBER>"
},
{
"type":{
"coding":[
{
"system":"http://terminology.hl7.org/CodeSystem/v2-0203",
"code":"PRN",
"display":"Provider number"
}
],
"text":"Provider Number"
},
"value":"<USER'S UUID>",
"assigner":{
"reference":"Organization/f-<SSO FACILITY ID>"
}
}
],
"name": [
{
"text": "<Full Name of Provider>",
"family": "<Last Name>",
"given": [
"<First Name>"
],
"suffix": [
"<Title>"
]
}
],
"telecom": [
{
"system": "email",
"value": "<User Email>"
}
],
"extension":[
{
"url":"https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-login",
"valueString":"<User Name>"
},
{
"url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-password",
"valueString": "<Password>"
}
]
}
]
}For more information, go to PractitionerRole.
Deactivating a User
To deactivate a user, set active to false and PUT the resource. DELETE is not supported on PractitionerRole.
Updated about 14 hours ago