Skip to main content
Use this when you have a patient’s paperwork (an intake form, referral letter or prior records) and want HealOS to write a note from it, with no recording.
Try it in a test organization first, with a document that holds only made-up details.
1

Create the patient

Expect 201. Save data.id as PATIENT_ID. If the patient already exists, you get 409 with existing.id; use that.
2

Upload the document

Send the file as multipart/form-data. PDF, JPEG, PNG and DOCX up to 10 MB are accepted, and the content must match the file extension.
Expect 201, data.status: "pending" and a message that ends in “text extraction started”. If message doesn’t mention extraction, start it yourself with POST .../documents/{documentId}/extract.
3

Wait for text extraction

Register a DOCUMENT_STATUS_CHANGED webhook, or poll every few seconds:
Expect data[0].status to move from pending to processing to completed, with has_extracted_text: true. On failed, read extraction_error.
4

Generate the note

Expect 202 with data.session_id. Save it as SESSION_ID.
Each call creates a new session and note. Don’t retry after a 202; check the session in the next step.
5

Read the note

Wait for a NOTE_CREATED webhook, or poll every 10 seconds:
Expect 200. data.notes is empty until the note is written, then holds it with its content and codes.

The same flow in Python

The steps above as one script, using requests (pip install requests). It reads the key from HEALOS_API_KEY and expects a test file holding only made-up details next to it.
document_to_note.py
In production, replace the two polling loops with the DOCUMENT_STATUS_CHANGED and NOTE_CREATED webhooks.

Expected outcomes