Lab Ordering Tenant Setup
Health Gorilla provisions and configures your tenant during implementation, including settings, licenses, laboratory account numbers, and API credentials.
If you onboard practices that place orders, rather than ordering only through your organization, choose your tenancy structure before implementation starts because changing it later requires reprovisioning.
Two structures are possible:
- A single tenant with one location per practice, which is simpler to run because everything sits in one place
- A sub-tenant for each practice, giving each its own clinical users, locations, and laboratory accounts, which keeps users and orders scoped to one practice at a time
That choice determines how many tenants are configured, and each one goes through the same setup.
To configure a tenant, provide:
- Organization name
- Region
- Ordering locations
- Laboratory account numbers you order under
- Initial user list
Account numbers are attached to your locations, and for some laboratories, like LabCorp, they are attached to clinical users as well.
In return, you receive:
- Tenant identifier
- Client identifier and secret, delivered securely
- List of approved API scopes
The client secret is shown once and cannot be retrieved afterwards. Store it in your password or secret manager the moment you receive it rather than planning to fetch it later.
Scopes
The access token you present must carry the scope the operation requires. Ordering and provisioning are each controlled by a capability scope. Both apply only to the iFrame's own calls, and standard FHIR access does not require either.
| Scope | What It Covers |
|---|---|
place_orders | Launching the iFrame and submitting orders. A missing place_orders scope is the most common cause of an authorization failure at launch |
create_users | Provisioning clinical and non-clinical users through the PractitionerRole endpoint |
Retrieving orders and results is authorized separately. Those calls go to the FHIR R4 endpoints, where access rules are built from SMART clinical scopes rather than the capability scopes.
A clinical scope takes the form patient, user, or system, then the resource and operation, as in system/RequestGroup.read. Reading orders and results needs read access to RequestGroup, ServiceRequest, DiagnosticReport, and Observation.
Environments
Health Gorilla provides two environments, each with its own base URL. OAuth 2.0 credentials are issued per environment and tied to a specific tenant. Build and test in the sandbox environment before moving to the production environment.
| Environment | Base URL |
|---|---|
| Sandbox | https://sandbox.healthgorilla.com/fhir/R4 |
| Production | https://api.healthgorilla.com/fhir/R4 |
Tenant configuration may not be identical between the two environments. If behavior differs, contact Health Gorilla to confirm which settings are applied in each.
Multi-Tenant and Channel Partner Builds
The choice between the two structures shapes how you provision users, how laboratory accounts resolve, and what each launch payload must specify. Under the sub-tenant model, Health Gorilla provisions each practice beneath your parent organization.
You can automate sub-tenant creation through the FHIR API. However, Health Gorilla sets the laboratory account numbers, product licenses, and OAuth 2.0 credentials for each sub-tenant.
Four things follow from the sub-tenant model:
- One tenant per user, with the
organizationreference on thePractitionerRoletargeting the right practice - One tenant per launch, ensuring each practice sees only the laboratories, locations, and clinical users configured for that practice
- Tenant-scoped orders and results, requiring you to iterate tenants rather than issue one query
- New practices after go-live, added within the structure you chose rather than replacing it
Enabling a Clinical User as an Ordering Provider
Creating a clinical user does not on its own make that user able to order. The ordering provider on a lab order is a clinical user who also carries a National Provider Identifier (NPI) and a laboratory account number. Those account numbers, along with product licenses and OAuth 2.0 credentials, are set by Health Gorilla rather than through the API. For the provisioning calls, go to Create a Clinical User.
Only clinical users appear in the Ordering Physician field. A non-clinical user is created the same way, omitting the NPI and using an administrative role, and cannot be selected as the ordering provider. The clinical user's name and NPI must match the Health Gorilla NPI directory exactly.
When a new clinical user cannot order from a particular laboratory, the usual cause is an account number that has not been attached. Quest and LabCorp hold account numbers in different places, and the symptom differs by laboratory, which is worth knowing on both sides of a support conversation.
| Account Number | Quest | LabCorp |
|---|---|---|
| Where it lives | Tenant level only, held per Business Unit and selected in Requisition Settings | Two account numbers, one at tenant level and a second on each clinical user |
| If it is missing | The name appears with no account number beside it, and the order cannot be submitted | The name does not appear in the list at all |
Health Gorilla confirms when a clinical user's configuration is complete. There is nothing to subscribe to, and you can't find out sooner by polling. Once a clinical user has an account number the Health Gorilla side is done, though enabling the practice at the laboratory is a separate step that is not visible in the iFrame.
Tenant Settings to Request
Health Gorilla applies each setting during implementation, and your users see the effect. As a result, Health Gorilla recommends that you finalize settings before go-live.
| Setting | Effect |
|---|---|
| Requisition Settings | Only the selected laboratories appear in the directory, under the chosen Quest Business Unit accounts |
| Laboratory account numbers | A clinical user becomes selectable as the ordering provider, and orders are billed against the matching account |
| Vendor list | Only named laboratories appear, in the directory and in search results |
| Ordering locations | Only the configured locations are selectable, each carrying its own accounts and address |
| Product licenses | Only the enabled products are available on the tenant |
| Lock the ordering provider | Users cannot change the prefilled ordering provider |
| Lock the patient | Users cannot change the patient in the iFrame |
| Prevent demographic changes | Users cannot edit demographics or insurance, but can still add missing required information |
| Diagnosis required on all orders | A diagnosis is required on every order, regardless of billing type |
| Quick Order changes | Existing Quick Orders can be renamed or deleted |
| Additional tenants | More tenants can be added after go-live |
Most of these follow from your build. However, three are judgment calls, where either answer is defensible and the right one depends on how your practices work.
- Lock the ordering provider, fixing it to the signed-in clinical user instead of leaving it open for practices whose staff order for several providers
- Prevent demographic changes, keeping your system the system of record for patient data
- Diagnosis required on all orders, against the default of requiring one only for third-party billing
Updated about 5 hours ago