Lab Requisitions and Results

A Lab Interaction carries two kinds of document: the paperwork that ordered the lab, and the report the lab returned. Hint types each one so your sync tells them apart by reading a field.

Use files for every other document on a Lab Interaction. Hint stores it beside the typed ones and reports its type as null, the same value a file attached before typing shipped reports. The two typed fields are an addition to files, and files carries whatever it carried before.

Every other part of file handling is shared with the rest of the interaction types. Read Interaction Files for the entry form, the download endpoints, and what an empty files array does.

Attach a requisition or a result

A file gets its type from the field you send it in. Create Lab Interaction and Update Lab Interaction accept two file fields:

Send both fields at the top level of the body, beside the rest of the lab data. Neither field belongs inside order or results.

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

The sample below shows the file fields only:

{
  "requisition_files": [
    { "url": "data:application/pdf;base64,JVBERi0xLjQKJVBFWEFNUExF", "filename": "requisition-000123.pdf" }
  ],
  "result_files": [
    { "url": "data:application/pdf;base64,JVBERi0xLjQKJVJFU1VMVFM=", "filename": "cbc-panel.pdf" }
  ]
}

Both fields take the same entry as files, so an https URL works as well as a data: URI, and filename is optional. Interaction Files covers the entry in full. Send a filename with a data: URI: Hint otherwise derives the name from the bytes, and returns a 422 when it cannot.

Read the interaction back to see what is attached. Each file you sent carries the matching type in the files array, and its id is the id you pass to the download endpoints.

Both fields only ever add

requisition_files and result_files add to the interaction's file list:

• Leave the field out and the interaction keeps its current files.
• Send an empty array beside another field and the interaction keeps its current files. An empty array attaches nothing.

So a PATCH that sends only result_files attaches those documents and keeps every file already on the interaction, including a requisition from an earlier request.

Hint rejects an update whose only field is an empty typed list with a 400. Send an empty array beside a field that carries a change.

A typed file survives the legacy clear

files: [] removes every untyped file on an interaction. A requisition or a result belongs to a separate list, so it stays attached and keeps appearing in the files array.

Send structured values and the PDF report

For partners and practices with API Access, the recommended payload includes both structured results and the report PDF in result_files, when both are available:

• Structured results support clinical review, numeric Lab Trends, and existing AI lab summaries where available.
• result_files give clinicians a report to open, download, or email, and give patients a report to download after the practice enables Member Access (patient_access: true).
• requisition_files keep the order paperwork separate for clinicians. Typed requisitions are not exposed in the shared patient lab.

A PDF does not create structured result values, and structured values do not generate a PDF. Send each document in its intended field rather than placing a requisition in the untyped files list. Untyped attachments can be patient-visible when the lab is shared.

Where clinicians find the files

On a saved lab, the footer offers Requisition PDF and Results PDF when the corresponding files exist. Multiple files are listed individually. Each file offers Open, Download, and Email; Email opens a draft with that file attached. The partner app, when available, sits inside Details, leaving Notes and the footer available in the same window.

Typed files are supplied through the API. Attaching a general file in Notes does not classify it as a requisition or result. Clinicians cannot remove an individual typed file from this footer; API clients use Delete a single file.

Sharing through Hint's patient portal

The practice controls sharing through Member Access or Notify Patient. Sharing is available when the interaction is Fulfilled, Signed, or Addended, including PDF-only labs. A Sent lab cannot be shared through these controls. Neither a PDF upload nor notify on a public API request shares the lab with the patient.

When Member Access is on (patient_access: true), the patient can open the lab in the patient portal and download its result files. Turning Member Access off removes patient access to that lab and its files. Typed requisition files stay hidden. Untyped attachments may also be visible, so keep requisitions in requisition_files.

The public lab read exposes patient_access. The public lab create and update endpoints do not accept it as a sharing control. See Lab Interactions for status and notification behavior.

Downloading a report into your own application

To display the report in your own application, select the file whose type is "lab_result" from the interaction's files array and request its download_url. These are practice-scoped Provider API endpoints, not patient-portal links.

If your application shows or sends the report to a patient, first read the Lab Interaction and require its current patient_access value to be true. This applies to structured results, report content, and file links. If the value is false, missing, or cannot be verified, do not expose them to the patient. A successful Provider API download is practice access, not permission to share with a patient.

Check again before each patient-facing display, download, or notification that exposes results or a file link. If Member Access is turned off, stop exposing the lab and its files, including cached patient-facing copies. A fulfilled status, attached PDF, or existing signed URL does not replace this check. Never include typed requisition files in the shared patient lab. See Respect patient access in your integration.

Interaction Files covers the endpoint, API version availability, and five-minute expiry. Request a fresh signed URL when needed rather than storing it as a permanent patient link.