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 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.

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. 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.