Technical Requirements

Your system must support secure, standards-compliant interaction with Health Gorilla’s FHIR R4 APIs.

• Use the staging environment for testing and the production environment for live traffic; remember, each environment has separate base URLs and credentials.
• Use OAuth 2.0 authentication with system-level credentials and the appropriate scopes for ordering and results.
• Configure a secure HTTPS endpoint to receive event delivery through FHIR Subscription.
• Support the following FHIR R4 resources: RequestGroup, ServiceRequest, Specimen, DiagnosticReport, Observation, DocumentReference, Subscription, and OperationOutcome.
• Align all ordered test codes to the selected laboratory’s compendium; and maintain mappings to your local catalog to ensure compatibility and complete order payloads.
• If your tenant supports multiple laboratories, orders that include tests from more than one vendor trigger Health Gorilla’s pre-submission split logic to ensure proper routing before transmission.
• Support status tracking and resource linkage (for example, DiagnosticReport.basedOn → RequestGroup).

Configure credentials and access

1. Request YOUR_CLIENT_ID and YOUR_CLIENT_SECRET from Health Gorilla.
2. Obtain an access token using OAuth 2.0 and confirm successful authentication.
3. Verify that the required scopes are granted for ordering, subscriptions, and results retrieval.

Set up event delivery

1. Configure a secure HTTPS endpoint to receive subscription notifications.
2. Create a Subscription for RequestGroup (order status) and DiagnosticReport (results).
3. Confirm that notifications are delivered and processed successfully.

Validate compendium alignment

1. Retrieve the laboratory’s compendium and test metadata.
2. Map your local test catalog to vendor codes and required Ask-at-Order-Entry (AOE) questions.
3. Validate that each order references supported codes and includes complete AOE responses.

Establish specimen handling

1. Create Specimen resources with type, collection details, and container data.
2. Reference the same Specimen from ServiceRequest and resulting Observation resources for traceability.

Operational Requirements

Operational readiness ensures that orders meet laboratory and regulatory expectations.

• Register ordering providers and facilities with valid identifiers (for example, National Provider Identifier).
• Normalize patient demographics to improve matching and reduce rejections. For example:
  • Use complete and consistent field formatting.
  • Follow USPS address standards.
  • Avoid abbreviations that differ from HL7 or FHIR conventions.
  • Ensure phone numbers are E.164-formatted (for example, +1-555-123-4567).
  • Populate demographic extensions (such as, race, ethnicity, or birth sex) when available.
• Confirm that each ordering location is registered and active with all participating laboratories.
• Define how your team handles validation errors, rejections, and warning responses.
• Integrate results into clinical review, decision support, and audit reporting.
• Document roles for integration engineering, operations, and release management to ensure clear accountability during onboarding and go-live.

Contract Readiness

Contractual onboarding enables Lab Network routing and compendium access for your tenant.

• Execute a lab-ordering agreement with Health Gorilla that defines permitted use cases.
• Select participating laboratories and define routing configurations.
• Acknowledge any vendor-specific policies for delivery mode, required AOEs, or document formats.
• Confirm that your tenant is provisioned for ordering and results in the staging environment before moving to production.

Go-Live Checklist

Confirm that all setup areas are complete before submitting live orders.

• Verify OAuth 2.0 credentials and token flow.
• Test and authenticate the FHIR Subscription endpoint.
• Retrieve and map the laboratory compendium.
• Validate specimen creation and linkage end-to-end.
• Register provider and facility identifiers.
• Validate patient demographic normalization.
• Confirm DiagnosticReport and Observation retrieval.
• Implement OperationOutcome error handling.