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.

Showing a result to a patient

To put a lab's PDF report in front of a patient, take the file whose type is "lab_result" from the interaction's files array and request its download_url. Typing is what makes that selection reliable: before it, the report had to be told apart from the requisition by its filename. Interaction Files covers the endpoint and the five-minute expiry.