Lab Network iFrame

The Lab Network iFrame is an embedded ordering experience that allows users to place diagnostic orders within your system using the Lab Network ordering interface, without a custom ordering UI. The iFrame does not support result display or retrieval.

What the iFrame Provides and What You Build

Embedding the iFrame removes the need to assemble orders yourself. You do not build a RequestGroup, resolve compendium test codes, retrieve Ask at Order Entry questionnaires, or match laboratory accounts to performers. The frame does all of that from the user's selections.

What it does not remove is the work on either side of the frame. You still need to provision the tenant and its users, launch the frame with a correctly formed patient payload, and retrieve orders and results afterwards for display. Those three responsibilities are the substance of an iFrame integration.

Ordering Capabilities

The primary function of the iFrame is embedded order entry.

Through the iFrame, users can:

• Place diagnostic orders within your system workflow
• Select the ordering facility and ordering provider
• Confirm patient context
• Choose requested tests based on configured compendia

Orders placed through the iFrame follow the same validation, compendium alignment, routing, and fulfillment rules as API-based or UI-based orders.

Prerequisites

iFrame access requires:

• An enabled Lab Network tenant
• Configured laboratory connections and compendium alignment
• OAuth 2.0 credentials with appropriate ordering scopes

The iFrame uses the same underlying Lab Network configuration as API-based ordering, including routing rules and test catalog alignment.

The iFrame does not require FHIR integration for order placement. Results handling requires API-based access or use of the UI. Provisioning users and providers is the one exception, and it runs through the FHIR PractitionerRole endpoint, which is creation rather than placement. Refer to Lab Ordering Tenant Setup for credentials, scopes, and the tenant settings Health Gorilla controls on your behalf, and to Create a Clinical User for the provisioning calls.

Launching the iFrame

The iFrame opens already authenticated, scoped to a single patient and a single order, and returns the user to a callback URL you supply. There is no Health Gorilla login and no navigation to any other part of the Health Gorilla interface. That isolation is intended behavior in embedded mode rather than a restriction on your account.

Launching takes four steps.

1. Post the patient payload to the Lab Network iFrame API, POST /doctor/api, which returns an order-entry URL.
2. Read the callback URL from the response.
3. Append a valid access token carrying the place_orders scope, as &access_token=.
4. Load the resulting URL in an embedded frame or browser window.

The Ordering Physician field follows the provider your token authenticates as. Where that provider holds a single account with the selected laboratory, the field is fixed to it; where they hold several, the user chooses.

The session is created for a specific patient by providing either patient demographics or an existing Health Gorilla patient ID. Using an existing patient ID ensures an exact match. When demographics are provided, patient matching rules are applied and a new patient may be created if no match is found. The patient context is resolved during session creation and is fixed for the duration of the session.

iFrame Request Example

A session request must carry four values: the placeOrder method, a facilityType that supports ordering, either patient demographics or a Health Gorilla patient identifier, and the callbackUrl the user returns to afterwards.

{
  "jsonrpc": "2.0",
  "method": "placeOrder",
  "params": [
    {
      "facilityType": "DiagnosticLaboratories",
      "callbackUrl": "https://yourapp.com/callback",
      "patient": {
        "className": "com.informedika.common.shared.vo.PatientVO",
        "firstName": "Jane",
        "lastName": "Doe",
        "gender": "female",
        "dateOfBirth": {
          "year": 1990,
          "month": 1,
          "day": 1
        }
      }
    }
  ]
}

The payload carries more than the patient. Insurance, guarantor, billing address, and visit identifiers are all prefilled on the ordering screen from the values you send, and the laboratory list the user chooses from follows from facilityType. iFrame Launch Payload Reference documents every field, whether it is required, and what each one changes on screen.

Patient Matching

When you send a full demographic payload rather than a patient resource identifier, one of three outcomes follows.

Send the patient resource identifier instead, and the match is exact. When your system holds the Health Gorilla patient identifier, using it on subsequent launches prevents both duplicate creation and the disambiguation prompt. Displaying Orders and Results covers retrieving the identifier from the order.

If the identifier is supplied and the patient does not exist, the request still returns HTTP 200 and reports the failure in the body instead. Your system has to detect it by reading the response, because the HTTP status will not show it. Refer to iFrame Launch Payload Reference for the status codes a response can carry.

Launch Errors

A sign-in prompt, a blank frame, or an authorization error at launch points to an expired or malformed token, or to a missing scope. A missing place_orders scope is the most common cause. Users cannot act on any of these, so handle them in your system rather than letting them surface in the frame.

A rejected payload comes back on the request itself, and no frame opens. Values must use the exact accepted casing, so a maritalStatus of Married is rejected when the accepted value is the lowercase married.

How an Order Travels

Most of the constraints on this surface follow from the path an order takes after launch.

1. Your system launches the frame for one patient.
2. The user builds the order and either submits or cancels it. A submitted order is validated for completeness and for valid test codes, and control returns to your system either way.
3. Health Gorilla converts the order into an HL7 message and transmits it to the laboratory electronically.
4. The laboratory collects and processes the specimen.
5. The laboratory returns results as HL7, and Health Gorilla matches them to the original order by the order number the laboratory returns, scoped to the tenant and the ordering facility.
6. Your system retrieves the order and the result and displays both to your users.

Note: Step 6 is yours. The iFrame has no order list, no order history, no reorder function, and no result display. Everything users need to see after selecting Submit comes from your system. Refer to Displaying Orders and Results.

The Four Ordering Stages

The user moves through four stages in sequence.

Every field on every stage is documented in Placing a Lab Order, including which are required and what users see when one is wrong. Point your support team at it rather than reproducing it in your help content.

Constraints of the Embedded Session

The frame holds no order state once a session ends, so your system has to cover three gaps:

• No order list, so a submitted order is not visible in the frame afterwards, including one scheduled for a future date
• No reorder function, so practices placing the same panels repeatedly should build Quick Orders during onboarding rather than copying a previous order
• No reachable draft, so a canceled order cannot be returned to and users rebuild it from the start

Results Handling

The iFrame does not display or provide access to results.

Handle results from iFrame orders through:

• API-based access for structured or document-based results
• Operational review in the UI

Results are ready when DiagnosticReport reaches the final status. Order status is not a readiness signal: it advances only once a final result reconciles back to the order, so orders can read as in progress while their results are already retrievable. Refer to Displaying Orders and Results for the queries.

Limitations

The iFrame is limited to order placement and does not support:

• Longitudinal result viewing
• Downstream data ingestion

Automated workflows, analytics, and clinical integration require API-based access.