PractitionerRole Create

Use the FHIR PractitionerRole endpoint to create accounts in Health Gorilla. PractitionerRole links a Practitioner resource to an organization and defines the person’s role within it.

Two account types are supported:

Clinician accounts must include a National Provider Identifier (NPI) and practitioner roles.
Non-clinician accounts do not require an NPI and are assigned only administrative or security roles.

The create_users scope is required for both account types.

Shared PractitionerRole Attributes

Attribute	Required	Notes
`resourceType`	Yes	Always `PractitionerRole`.
`meta`	Yes	Must include a profile. Optional tag values can disable email invitations `VERIFIED` or notifications `NO_SUBSCRIPTIONS`.
`active`	Yes	Must be `true` when creating accounts.
`practitioner`	Yes	Reference to the contained `Practitioner` resource.
`code`	Yes	Must include appropriate role values.
`organization`	No	Use to create an account in a different tenant.

Example: Control Invitations and Notifications

  "meta": {
  "tag": [
    { "system": "https://www.healthgorilla.com", "code": "VERIFIED" },
    { "system": "https://www.healthgorilla.com", "code": "NO_SUBSCRIPTIONS" }
  ]
}

Shared Practitioner Attributes

Attribute	Required	Notes
`resourceType`	Yes	Always `Practitioner`.
`id`	Yes	Referenced by `PractitionerRole.practitioner`.
`meta`	Yes	Must include a profile.
`identifier`	Varies	Clinicians must include NPI. Non-clinicians may include a UUID for single sign-on.
`name`	Yes	Real name of the account holder. Must match the NPI directory entry for clinicians.
`telecom`	No	Can include an email address.
`extension`	Yes	Must include a username. May include a password if direct login to the Health Gorilla user interface is required.

  "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>"
    }
  ]

Clinician Accounts

Clinician accounts represent licensed providers and must include a National Provider Identifier.

Identifiers

Practitioner.identifier must include the NPI.
Optional identifiers can include laboratory account numbers or UUIDs for single sign-on.

Example: NPI Identifier

  "identifier": [
    {
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "<NPI NUMBER>"
    }
  ]

Example: Lab Account Identifier

  "identifier": [
    {
      "type": { "text": "Account number" },
      "assigner": { "reference": "Organization/f-<Lab Facility ID>" },
      "value": "<LAB ACCOUNT NUMBER>"
    }
  ]

Example: UUID for SSO

  "identifier": [
  {
    "type": { "text": "Provider Number" },
    "value": "<UUID>",
    "assigner": { "reference": "Organization/f-<SSO FACILITY ID>" }
  }
]

Roles

Use PractitionerRole.code to define administrative and practitioner roles.

  "code": [
  {
    "coding": [
      {
        "system": "https://www.healthgorilla.com/administrative-role",
        "code": "provider",
        "display": "Provider"
      },
      {
        "system": "http://hl7.org/fhir/practitioner-role",
        "code": "doctor",
        "display": "Doctor"
      }
    ]
  }
]

Non-Clinician Accounts

Non-clinician accounts represent staff such as office managers, billing staff, or nurses who do not have an NPI.

Identifiers

Practitioner.identifier does not include an NPI.
Optional UUID may be included for single sign-on.

Example: UUID for SSO

  "identifier": [
  {
    "type": { "text": "Provider Number" },
    "value": "<UUID>",
    "assigner": { "reference": "Organization/f-<SSO FACILITY ID>" }
  }
]

Roles

Use PractitionerRole.code to define an administrative role.

  "code": [
  {
    "coding": [
      {
        "system": "https://www.healthgorilla.com/administrative-role",
        "code": "officeManager",
        "display": "Office Manager"
      }
    ]
  }
]

Security Roles

Use a PractitionerRole extension to assign a security role such as administrator, readonly, or staff.

  "extension": [
  {
    "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/practitionerrole-security-role",
    "valueCodeableConcept": {
      "coding": [
        {
          "system": "https://www.healthgorilla.com/security-role",
          "code": "administrator",
          "display": "Administrator"
        }
      ],
      "text": "Administrator"
    }
  }
]

Full Examples

Clinician Account

  {
  "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": "#pr1" },
  "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": "pr1",
      "meta": {
        "profile": [
          "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner",
          "https://healthgorilla.com/fhir/StructureDefinition/hg-practitioner"
        ]
      },
      "identifier": [
        { "system": "http://hl7.org/fhir/sid/us-npi", "value": "<NPI NUMBER>" },
        { "type": { "text": "Account number" }, "assigner": { "reference": "Organization/f-<Lab Facility ID>" }, "value": "<LAB ACCOUNT NUMBER>" },
        { "type": { "text": "Provider Number" }, "value": "<UUID>", "assigner": { "reference": "Organization/f-<SSO FACILITY ID>" } }
      ],
      "name": [
        { "text": "<Full Name>", "family": "<Last Name>", "given": ["<First Name>"], "suffix": ["<Title>"] }
      ],
      "telecom": [
        { "system": "email", "value": "<Email>" }
      ],
      "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>" }
      ]
    }
  ]
}

Non-Clinician Account

  {
  "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": "#nc1" },
  "code": [
    {
      "coding": [
        { "system": "https://www.healthgorilla.com/administrative-role", "code": "staff", "display": "Staff" }
      ]
    }
  ],
  "extension": [
    {
      "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/practitionerrole-security-role",
      "valueCodeableConcept": {
        "coding": [
          { "system": "https://www.healthgorilla.com/security-role", "code": "administrator", "display": "Administrator" }
        ],
        "text": "Administrator"
      }
    }
  ],
  "contained": [
    {
      "resourceType": "Practitioner",
      "id": "nc1",
      "meta": {
        "profile": ["https://healthgorilla.com/fhir/StructureDefinition/hg-practitioner"]
      },
      "identifier": [
        {
          "type": { "text": "Provider Number" },
          "value": "<UUID>",
          "assigner": { "reference": "Organization/f-<SSO FACILITY ID>" }
        }
      ],
      "name": [
        { "use": "official", "text": "<Full Name>", "family": "<Last Name>", "given": ["<First Name>"] }
      ],
      "telecom": [
        { "system": "email", "value": "<Email>", "use": "work" }
      ],
      "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>" }
      ]
    }
  ]
}