Clinical Notes

The notes endpoints let you pull clinical notes out of Healos — one at a time, by session, as a filtered list, or as a bulk export. Every note carries its medical codes, and you can request the session transcript and patient context alongside it. All notes endpoints require the notes:read scope. Access is scoped to your organization: you see notes authored by members of your org.

patient_id is a BigInt serialized as a string — treat it as an opaque string, same as elsewhere in the API. See Making Requests.

List Notes

Lightweight, paginated list. Use it to discover note IDs; fetch full content with Get a Note or Export.

curl "https://api.healos.ai/ext-api/v1/notes?limit=20" \
  -H "X-API-Key: hlsk_your_key_here"

{
  "data": [
    {
      "id": "9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e",
      "patient_id": "481926357104938271",
      "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "note_type": "clinical_visit",
      "specialty": "Cardiology",
      "template_id": "7a1c...",
      "template_name": "Follow-Up Patient Visit",
      "created_at": "2026-03-15T09:30:00.000Z",
      "updated_at": "2026-03-15T10:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total_pages": 1 }
}

Filters

Both GET /notes and GET /notes/export accept the same filters:

Query param	Description
`patient_id`	Notes for one patient
`session_id`	Notes for one session
`template_id`	Notes generated from a template
`created_by`	Notes authored by a specific clinician (must be in your org)
`note_type`	e.g. `clinical_visit`
`from`	Created on/after this date (ISO 8601, e.g. `2026-01-01`)
`to`	Created on/before this date (ISO 8601)

curl "https://api.healos.ai/ext-api/v1/notes?patient_id=481926357104938271&from=2026-01-01&to=2026-06-30" \
  -H "X-API-Key: hlsk_your_key_here"

Get a Note

Returns the full note — content, problems, procedures, icd10_codes, cpt_codes — with the session transcript and patient context embedded by default.

curl https://api.healos.ai/ext-api/v1/notes/9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e \
  -H "X-API-Key: hlsk_your_key_here"

{
  "data": {
    "id": "9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e",
    "patient_id": "481926357104938271",
    "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "note_type": "clinical_visit",
    "specialty": "Cardiology",
    "template_name": "Follow-Up Patient Visit",
    "created_at": "2026-03-15T09:30:00.000Z",
    "content": "Chief complaint: ...",
    "problems": ["Hypertension"],
    "procedures": ["12-lead ECG"],
    "icd10_codes": { "I10": "Essential hypertension" },
    "cpt_codes": { "Office visit": [{ "code": "99213", "description": "Established patient" }] },
    "transcript": {
      "text": "Doctor: ... Patient: ...",
      "summary": "Patient stable on current regimen.",
      "title": "Follow-up visit",
      "status": "completed",
      "session_date": "2026-03-15T09:00:00.000Z",
      "start_time": "2026-03-15T09:00:00.000Z",
      "end_time": "2026-03-15T09:30:00.000Z"
    },
    "patient": {
      "id": "481926357104938271",
      "name": "Maria Santos",
      "pronouns": "she/her",
      "date_of_birth": "1985-04-12",
      "client_history": {
        "medical_history": "...",
        "family_history": "...",
        "social_history": "...",
        "previous_treatment": "..."
      }
    }
  }
}

Controlling embedded blocks

The note body and medical codes are always returned. Control the heavier embedded blocks with the include query param — a comma-separated list of transcript and patient. It defaults to both.

# Omit both embedded blocks (note body + codes only)
curl "https://api.healos.ai/ext-api/v1/notes/{noteId}?include=" \
  -H "X-API-Key: hlsk_your_key_here"

# Transcript only
curl "https://api.healos.ai/ext-api/v1/notes/{noteId}?include=transcript" \
  -H "X-API-Key: hlsk_your_key_here"

When excluded, transcript and patient are returned as null.

Notes by Session

Returns every note for a session, plus the session’s transcript/summary and the patient context, in one call. Returns 404 if the session isn’t owned by your organization.

curl https://api.healos.ai/ext-api/v1/sessions/f47ac10b-58cc-4372-a567-0e02b2c3d479/notes \
  -H "X-API-Key: hlsk_your_key_here"

{
  "data": {
    "session": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "patient_id": "481926357104938271",
      "transcript": { "text": "...", "summary": "...", "title": "Follow-up visit" }
    },
    "patient": { "id": "481926357104938271", "name": "Maria Santos" },
    "notes": [ { "id": "9b2d...", "content": "...", "icd10_codes": {} } ]
  }
}

Export Notes

GET /notes/export returns all notes matching the filters above (no pagination), with full content, codes, transcript, and patient context on each note. Pick the format with ?format=:

`format`	Response	Notes
`json` (default)	`{ "data": [...], "meta": { "count", "truncated" } }`	Capped at 1000 notes
`csv`	`text/csv` attachment	Flattened, one row per note. Capped at 1000 notes
`ndjson`	`application/x-ndjson` stream	One JSON note per line. No cap — use this for large pulls

# JSON (default), filtered to one patient
curl "https://api.healos.ai/ext-api/v1/notes/export?patient_id=481926357104938271" \
  -H "X-API-Key: hlsk_your_key_here"

# CSV download
curl "https://api.healos.ai/ext-api/v1/notes/export?format=csv&from=2026-01-01" \
  -H "X-API-Key: hlsk_your_key_here" -o notes.csv

# NDJSON stream (recommended for full exports)
curl "https://api.healos.ai/ext-api/v1/notes/export?format=ndjson" \
  -H "X-API-Key: hlsk_your_key_here" -o notes.ndjson

json and csv are capped at 1000 notes. When the result is capped, json sets meta.truncated: true and csv sets the X-Result-Truncated header. To pull more than 1000 notes, narrow the date range with from/to, or use format=ndjson, which streams the full set with no cap.

The CSV columns are: note_id, patient_id, patient_name, session_id, session_date, note_type, specialty, created_at, problems, procedures, icd10_codes, cpt_codes, content, transcript. Array and code fields are flattened into a single cell.

Getting Started

Resources

Clinical Notes

Clinical Notes

List Notes

Filters

Get a Note

Controlling embedded blocks

Notes by Session

Export Notes

​Clinical Notes

​List Notes

​Filters

​Get a Note

​Controlling embedded blocks

​Notes by Session

​Export Notes

Clinical Notes

List Notes

Filters

Get a Note

Controlling embedded blocks

Notes by Session

Export Notes