iFrame Launch Payload

As a developer embedding the Lab Network iFrame, you build the launch payload that opens each ordering session. It carries the patient the session opens for, the prefilled billing details your system already holds, and the callback URL the user returns to afterwards. You choose the kind of facility with facilityType, and the laboratories that appear in the directory come from your tenant configuration.

Every field is marked required or optional, with the values it accepts and what it changes on the ordering screen. That matters while you are building the call, and again when a launch does not behave as expected. Three cases come up most: a field on the ordering screen is empty, a field is prefilled with something unexpected, or a launch is rejected before the frame loads.

The Session Request

Post the payload as a JSON-RPC 2.0 request to POST /doctor/api, with a bearer token carrying the place_orders scope. Credential and scope information is available on the Lab Ordering Tenant Setup page.

Each session takes one request and covers one patient and one order. The whole payload sits in a single object inside params, so one call contains every field for the patient, insurance, guarantor, and billing.

Every object in the payload except an address and a date carries a className naming its type. The patient, and each insurance, insurance provider, and insured party all need one, and a request that omits it is rejected.

POST /doctor/api HTTP/1.1
Authorization: Bearer <your_access_token>
Host: api.healthgorilla.com

{
  "id": 8,
  "jsonrpc": "2.0",
  "method": "placeOrder",
  "params": [
    {
      "facilityType": "DiagnosticLaboratories",
      "callbackUrl": "https://yourapp.com/neworder/callback",
      "state": "1",
      "patientId": "59f71f62e8f8cc8cbe17cfd7"
    }
  ]
}

Values are case sensitive, so a maritalStatus of Married is rejected when the accepted value is the lowercase married. The rejected payload comes back on the request itself. Your system catches it and no frame opens.

Top-Level Parameters

Seven parameters sit at the top level of the request, outside the patient object. Send patientId rather than patient when your system already knows the identifier, because an exact match avoids both duplicate patient creation and the disambiguation prompt.

A state value comes back on your callback URL unchanged, so your system can tie a completed order to the session that started it, and a visitId stays on the order for your records. Neither appears on the ordering screen. Sending overwritePatientInsurances as true replaces the insurances already held for a matched patient rather than adding to them.

The callbackUrl you send is not the callbackUrl you get back. The one you send is where the user is redirected at the end of the session, and the one in the response is the session URL you load in the frame.

Ordering Facility Types

Send facilityType to define what kind of facility an order is going to. You choose a category rather than a particular lab, and which laboratories appear inside it comes from your tenant configuration.

The platform has 20 facility types and 13 of them support ordering. The other seven exist for directory and routing, and a request carrying one of them is rejected before the frame loads with "Bad request" . does not support ordering.

Patient Demographics

The first time you open a session for a patient, before your system has a Health Gorilla patient identifier, send a patient object. The demographics are matched against existing patients, and a new patient is created when nothing matches.

Optional fields are worth sending because address and contact details sharpen matching and keep duplicate patients from accumulating across launches.

Patient Identifier

After the first session, when your system already holds the patient identifier, send patientId. For details on retrieving the identifier from the order, go to Displaying Orders and Results.

The match is exact, so no disambiguation prompt reaches the user and no duplicate patient is created. An identifier for a patient that does not exist fails the request with an invalid-patient error carrying that identifier.

Address Object

The patient, guarantor, and insurer each take an address, and all three use the same shape. Send country only for addresses outside the United States, because it defaults to USA when you send neither a country nor a state, and a state implies its own country.

Local Date Object

Dates are sent as three numeric fields rather than a formatted string, which removes any ambiguity about date order. On the patient and guarantor, date-of-birth fields take this shape. Values are numbers rather than zero-padded strings, so January is 1, for example.

Insurance

Insurance sits on the patient object in up to three slots: primaryInsurance, secondaryInsurance, and tertiaryInsurance. Send it to prefill the payer when billing is set to Third Party, which is also the billing type that makes a diagnosis code mandatory. Every insurance must carry an insured block, and a request without one fails with Missing "insured" block.

A full insurance block shows the nesting and the className on each level.

{
  "className": "com.informedika.common.shared.vo.PatientVO",
  "firstName": "Jane",
  "lastName": "Doe",
  "gender": "female",
  "dateOfBirth": { "year": 1990, "month": 1, "day": 1 },
  "primaryInsurance": {
    "className": "com.informedika.common.shared.vo.InsuranceVO",
    "provider": "Blue Shield",
    "policyId": "123456789",
    "providerInfo": {
      "className": "com.informedika.common.shared.vo.BaseInsurerVO",
      "name": "Blue Shield",
      "phone": "8005551212",
      "address": {
        "address1": "PO Box 272850",
        "city": "Chico",
        "state": "CA",
        "zip": "95927",
        "country": "USA"
      }
    },
    "insured": {
      "className": "com.informedika.common.shared.vo.GuarantorVO",
      "firstName": "Jane",
      "lastName": "Doe",
      "relationship": "self"
    }
  }
}

Send the patient object as the patient value inside params.

Insurance Provider Object

The providerInfo object holds the payer's identity and the claims address. name and address are both required, and a payload missing either fails with Bad request. Invalid insurer. Name, Address are required. phone is optional, but a missing payer phone is a routine cause of claim rejection at the laboratory, so send it when you have it.

Guarantor Object

Sent as insured on each insurance, the guarantor is a flat object that carries the guarantor's details and their relationship to the patient. First name, last name, and relationship are required, and a payload without them fails with Bad request. Invalidguarantor. FirstName, LastName, Relationship are required. When relationship is self, the guarantor is the patient and their details are sent again.

gender and dateOfBirth are optional in the request, but guarantor billing requires them, so send both when Bill To is set to Guarantor. For details on billing type requirements, go to the Billing and Accounts page.

Response

A successful response carries one field, the URL that opens the ordering screen. It is not the callbackUrl you sent. Yours is the redirect target at the end of the session, and this one is what you load to begin.

A failed request returns HTTP 200, reporting the failure in the body rather than in the status line. This makes it important to read the body on every call. Each failure carries a numeric code and a message.

A patient identifier that matches nothing returns code 4 with the message Patient with ID [<id>] not found.

{
  "jsonrpc": "2.0",
  "result": [
    {
      "callbackUrl": "https://healthgorilla.com/newsession?go=..."
    }
  ],
  "id": 8
}

To put the ordering screen in front of your user, append your OAuth 2.0 access token to that URL as an access_token parameter and load the result in a frame or a separate window. The token signs the user in, so they never see a Health Gorilla login.

Callback Parameters

When the user submits or cancels, they are redirected to the callbackUrl you supplied, with the outcome in the query string. You can supply a callback URL that already has parameters on it. When one is present, Health Gorilla appends with &. When no parameter is present, Health Gorilla appends with ?.

Two things need care. Treat canceled as an ordinary outcome rather than a failure, since a user abandoning an order is normal traffic. Also, read both orderId and orderIds. The two never appear together, so an order that splits during placement returns orderIds, and a system reading only orderId captures no identifier for that order.