Create a Clinical User
The PractitionerRole FHIR endpoint creates users and manages their universally unique identifiers (UUIDs). Two types of users can be created through the PractitionerRole endpoint. Clinical users have a National Provider Identifier (NPI). Non-clinical users, such as staff and office managers, do not have an NPI.
Each user is created with a PractitionerRole FHIR resource. Creating a clinical user has two parts: retrieving the Practitioner FHIR resource for the clinician, and creating the PractitionerRole FHIR 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 provider with specific tenant locations. When omitted, the provider 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 provider for Health Gorilla's Single Sign-On (SSO) option. |
name | Yes | Contains the provider's name. |
telecom | No | Adds the provider's email to the account. |
extension | Yes | Passes a required username and an optional password for the account. |
Creating a Clinical User
Retrieve the Practitioner Resource by NPI
When you create a clinical user, the user'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"
}
}
]
}Email Invitations and Notifications
The PractitionerRole.meta.tag array lets you decide whether an email invitation is sent to the created user, and whether the notifications set for a new user are turned off. By default, Health Gorilla sends an email invitation to new users to validate the account. To turn off the invitation, use the VERIFIED option in the tag array, as shown below.
By default, a new user account has email notifications turned on. To turn them off, use the NO_SUBSCRIPTIONS option in the tag array, as shown below.
The tag attribute is optional and is only used when the VERIFIED or NO_SUBSCRIPTIONS functionality is required.
"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. 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>"
}
]
}
]Location-Specific Account Numbers
The PractitionerRole.location array associates the provider with specific locations in the tenant. This field is optional. When location is omitted, the provider 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, binds 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 API Reference > PractitionerRole.
Updated about 23 hours ago