Lab Interactions

A Lab Interaction records one lab order for a patient: the order, the report from the lab, and the result values. This guide is for partners and practices with API Access that send lab data to Hint. It follows one order from the request to the results.

POST  /api/provider/patients/{patient_id}/interactions/lab
GET   /api/provider/patients/{patient_id}/interactions/lab/{id}
PATCH /api/provider/patients/{patient_id}/interactions/lab/{id}

The reference pages are Create Lab Interaction, Show Lab Interaction, and Update Lab Interaction. To attach the requisition and the result documents, read Lab Requisitions and Results.

Send structured results and the report PDF

Send both when they are available:

Data	Field	What it enables
Structured result values	`results`	Clinical review and numeric Lab Trends. Existing AI lab summaries use structured results, subject to their availability rules.
Result report PDFs	`result_files`	Clinicians can open, download, or email the report. When the practice enables Member Access (`patient_access: true`), patients can open and download its result files in the patient portal.
Requisition PDFs	`requisition_files`	Clinicians can access the order paperwork separately from the results. Typed requisition files are not included in the patient's shared lab.

Structured results and PDFs serve different purposes. Uploading a PDF does not populate Lab Trends or supply structured values for an AI summary. Sending structured results does not generate a result PDF. A PDF-only lab can still be shared by the practice when its status allows it.

Structured results were already supported. The typed document fields add a way to distinguish requisitions from result reports; they do not replace results.

Create a lab

Send the order when the provider orders the lab:

{
  "integration_record_id": "labco-ord-555",
  "vendor_order_id": "ORD-555",
  "status": "sent",
  "order": {
    "lab_reference_id": "ACC-1001",
    "ordered_from": "LabCo",
    "authored_on": "2026-10-01T10:00:00Z",
    "actions": [{ "reference": "CBC", "display": "Complete Blood Count" }]
  }
}

status is sent or fulfilled. If you leave it out, Hint uses sent.
If you send order, it must have lab_reference_id, ordered_from, and authored_on.
vendor_order_id is your order number. Hint returns it on the lab.

Hint returns the lab with its id, for example inter-2f93f9da35eb293f, and the patient_id of the patient. Store this id, or use your integration_record_id. Each one identifies the lab in an update.

Prevent duplicate labs

Send your own ID for the order in integration_record_id. If a lab with this integration_record_id already exists, Hint does not create a second lab. It returns a 409 with the location of the existing lab:

{
  "status": 409,
  "message": "There is already a interaction with this integration record id",
  "code": null,
  "errors": {
    "location": "/api/provider/patients/pat-ab12C345DeF6/interactions/lab/inter-2f93f9da35eb293f",
    "type": "Interaction",
    "id": null
  }
}

If a create request times out, send it again with the same integration_record_id. A 409 tells you that the first request created the lab, and location gives you its id.

A create request never changes an existing lab. To change a lab, use the update endpoint.

Do not use vendor_order_id to prevent duplicates. An update that sends order, report, or results removes vendor_order_id from the lab. After that, Hint cannot find the lab by it.

Update a lab

Put the lab id or your integration_record_id in the path:

PATCH /api/provider/patients/pat-ab12C345DeF6/interactions/lab/labco-ord-555

🚧
An update replaces the order, the report, and the results
Hint stores order, report, and results as one block. If an update sends one of them, Hint replaces the full block with the content of that request. Hint removes the parts that the request does not send, and it also removes vendor_order_id. Send order, report, and results together in every update that sends one of them.

Each field in the update body works in one of these ways:

Field	What the update does
`order`, `report`, `results`	Replaces all three with the content of the request. Hint removes a part that the request does not send.
`results`	Replaces the full list. Send every result of the lab, not only the new ones.
`status`, `event_timestamp`	Changes the value. If you leave the field out, the value does not change.
`requisition_files`, `result_files`	Adds files. See Lab Requisitions and Results. To remove one file, see Delete a single file.
`files`	Replaces the untyped files. `[]` removes them. See Interaction Files.
`notify`	Controls the Lab Results notification. See When Hint notifies the practice.

order.lab_reference_id and report.lab_reference_id are one value in Hint. Send the same value in both.

When the lab returns results

Send the full lab: the order again, the report, and every result.

{
  "status": "fulfilled",
  "order": {
    "lab_reference_id": "ACC-1001",
    "ordered_from": "LabCo",
    "authored_on": "2026-10-01T10:00:00Z",
    "actions": [{ "reference": "CBC", "display": "Complete Blood Count" }]
  },
  "report": {
    "status": "final",
    "issued": "2026-10-02T09:00:00Z",
    "lab_reference_id": "ACC-1001"
  },
  "results": [
    {
      "id": "res-1",
      "code": [{ "code": "718-7", "display": "Hemoglobin" }],
      "code_text": "Hemoglobin",
      "issued": "2026-10-02T09:00:00Z",
      "value_quantity": { "value": 14, "unit": "g/dL" }
    },
    {
      "id": "res-2",
      "code": [{ "code": "4544-3", "display": "Hematocrit" }],
      "code_text": "Hematocrit",
      "issued": "2026-10-02T09:00:00Z",
      "value_quantity": { "value": 42, "unit": "%" }
    }
  ]
}

Do not send only the part that changed. This update keeps the report and removes the order:

{
  "status": "fulfilled",
  "report": { "status": "final", "issued": "2026-10-02T09:00:00Z" }
}

After this request, the lab has no order, no results, and no vendor_order_id.

When only the status or the date changes

An update that sends no order, report, or results keeps all three. For example, this update changes the event time only:

{
  "event_timestamp": "2026-10-01T08:00:00Z",
  "notify": false
}

When Hint notifies the practice

When a lab is fulfilled, Hint creates a Lab Results notification for the practice. This occurs on the create and on every update after that. An update that only adds a file or changes the date also creates one.

To prevent a notification, send "notify": false. Send it on each update of a fulfilled lab that has no new results. If you leave notify out, Hint creates the notification.

What clinicians and patients see

Every saved lab opens with a header, accordion sections, and a footer. The header shows the current interaction status and the available order information. When the partner app is available, it appears inside Details, with Notes and the footer alongside the workflow. Without a partner app, Details shows the available order data, and a Results section appears when structured results exist. Numeric results support View Lab Trends.

Typed files appear in the footer under Requisition PDF and Results PDF (plural when there are several). Each group appears only when files exist. Clinicians can open, download, or email individual files. Notes let clinicians record their interpretation and sign it in Hint; the public Lab Interaction schema does not expose that interpretation note.

Patient access is a separate practice action

The practice shares the lab using Member Access or Notify Patient in Hint. Uploading results or setting notify does not grant patient access: notify controls the practice's Lab Results notification described above.

The clinical sharing controls accept the interaction statuses Fulfilled, Signed, and Addended. Sent is not shareable. This check uses the interaction status, not the presence of structured results or a result file, and not report.status. Send status: "fulfilled" when the lab's results are ready; the public create and update API accepts sent and fulfilled, while signing and addenda are clinical workflows.

Once the practice shares the lab, the patient can open it in the patient portal and download its result files. Typed requisition files are excluded; other untyped attachments can also be visible. Read Lab Requisitions and Results for the document distinction. The public lab read returns patient_access so an integration can observe the sharing state; it is not a writable field on the public lab create or update endpoints.

Respect patient access in your integration

Before showing a lab's structured results, report, or result files to a patient, read the Lab Interaction and require patient_access: true. This value reflects the practice's Member Access setting. If it is false, missing, or cannot be verified, do not display or send the lab results or file links to the patient.

A Fulfilled, Signed, or Addended status makes a lab eligible for sharing; it does not grant patient access. Neither a result PDF, the presence of structured results, notify, nor a successful Provider API file download authorizes patient disclosure. Provider API credentials can retrieve data for the practice even when patient access is off.

Check the current patient_access value before each patient-facing display, download, or notification that exposes results or a file link. If the practice turns Member Access off, stop exposing the lab and its files through your application, including cached patient-facing copies. Do not treat a previously issued signed file URL as proof of continuing access. Typed requisition files remain excluded from the shared patient lab even when patient_access is true.