Create a Clinical User
Overview
Health Gorilla uses the PractitionerRole FHIR endpoint for creating users and managing the associated UUIDs. See PractitionerRole for more details. Two types of users can be created via the PractitionerRole endpoint. Clinical users represent those users with NPI numbers. Non-clinical users represent staff, office managers, and other users without associated NPI numbers. Each user is created using a PractitionerRole FHIR resource. The process of creating a clinical user is detailed here. There are two parts to creating a clinical user, retrieving the Practitioner FHIR resource for the clinician and creating the PractitionerRole FHIR resource. This workflow is described below. More examples can be found at the Health Gorilla Git Repository.
The create_users scope is required when creating Users via the PractitionerRole API.
Supported Attributes of PractitionerRole Resource
| Attribute | Required | Notes |
|---|---|---|
| resourceType | Yes | Will always be "PractitionerRole" |
| meta | Yes | This field will contain a required a profile attribute as well as an optional "tag" attribute that controls email invitations and notifications for new users. |
| active | Yes | will always be set to "true" for creating new users |
| pracititioner | Yes | Will contain a reference to an internal Practitioner Resource that describes the user to be created |
| code | Yes | Will contain the required administrative-role and practitioner-role |
| organization | No | This field is used when creating a user in a different tenant (See Creating a Tenant) |
Supported Attributes of Internal Practitioner Resource
| Attribute | Required | Notes |
|---|---|---|
| resourceType | Yes | Will always be "Practitioner" |
| id | Yes | The ID of the resource. This ID is reference in the PractitionerRole.practitioner attribute. |
| meta | Yes | Will contain a required profile attribute |
| identifier | Yes | Will contain a required attribute representing the provider's NPI. Can also contain an optional attribute representing a lab account number. Can also contain an optional attribute that can be used to assign a UUID to the provider for using Health Gorilla's Single Sign On(SSO) option. |
| name | Yes | will contain the Provider's name |
| telecom | No | This attribute can be used to add the provider's email to the account. |
| extension | Yes | This attribute is use to pass a required username and an optional password for the account. |
Creating a Clinical User
Retrieve Practitioner FHIR Resource
Health Gorilla maintains an NPI directory of providers in the United States. When creating a Clinical User, the information of the user must match the information contained in the Health Gorilla NPI directory. The Practitioner FHIR Resource for the provider can be retrieved by querying the Practitioner FHIR endpoint with the Provider's NPI number. The Provider name attribute will be used to create the Practitioner Resource contained in the PractitionerRole resource and must match exactly.
Retrieve Practitioner Resource by NPI
{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"
}
}
]
}
Controlling Email Invitations and Notifications
The PractitionerRole.meta.tag array will allow you to decide if an email invitation will be sent to the created user as well as turning off any notifications set for a new user. By default, an email invitation is sent by Health Gorilla to new users. This email is sent to validate the account. This functionality can be turned off by using the "VERIFIED" option in the tag array per the example below.
By default, a new user account has email notifications turned on. You can turn off this functionality by using the "NO_SUBCRIPTIONS" option in the tag array per the example below.
The tag attribute is optional and is only used if the VERIFIED or NO_SUBSCRIPTIONS functionality is required.
"tag":[
{
"system":"https://www.healthgorilla.com",
"code":"VERIFIED"
},
{
"system":"https://www.healthgorilla.com",
"code":"NO_SUBSCRIPTIONS"
}
]
Setting the Administrative Role and Practitioner Role
The PractitionerRole.code array is used to set 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"
}
]
}
],
Setting the NPI for the Provider
The internal Practitioner resource uses the Pracitioner.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>"
}
]
}
]
Setting the Lab Account Number
The internal Pracitioner Resources uses an attribute in the Practitioner.identifier array to set the lab account(s) for the Provider. This field is optional.
"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>"
},
],
}
]
Creating a UUID for a User
Health Gorilla allows the use of Single Sign On. This can be used in conjunction with the Health Gorilla iframe. The internal Patient FHIR resource uses the Practitioner.identifier attribute to create the UUID. There is no specification 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>"
}
}
],
}
]
Setting the User's Real Name
The Practitioner.name attribute is used to pass the user's real name to Health Gorilla. This field MUST match the name attribute from the Practitioner FHIR resource that was retrieved in this step. 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>"
]
}
],
}
]
Setting the User's Email
The Practitioner.telecom attribute is used to pass the user's email to the user account. This field is optional.
"contained": [
{
"resourceType": "Practitioner",
......
"telecom": [
{
"system": "email",
"value": "<USER EMAIL>",
"use": "work"
}
]
}
]
Setting the Username and Password
Health Gorilla uses extensions to allow for creation of a username and password. The username is required for account creation. A password is optional and is only required if the user will log into the Health Gorilla UI via the Health Gorilla log in 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>"
}
]
}
]
Setting the Target Tenant (Only used for IPA customers)
Health Gorilla allows customers to manage multiple tenants if required by their business needs. In this workflow, the need exists to create users in multiple tenants. The organization attribute is used to pass the target tenant's unique identifier to Health Gorilla.
"organization": {
"reference": "Organization/t-111e1e656869ac26d411820e"
},
Clinical User Full Example
The following example payload is contains all available attributes. More examples can be found 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"
}
]
}
],
"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>"
}
]
}
]
}
Updated 5 months ago