Quickstart

This quickstart makes six calls with made-up data: it checks your key, creates a fake patient, writes a short note for them, reads it back and then deletes the patient. Run it in a test organization, not in the organization that holds your real patients.

Step 4 generates a real note and uses one Scribe session from the organization’s plan. Every other step is free.

Before you start

An org admin opens Account Settings → API Keys at app.healos.ai/account-settings in the test organization and creates a key with these scopes: patients:read, patients:write, notes:read, notes:write.
Copy the key (it starts with hlsk_ and is shown only once) and keep it in an environment variable, not in your code:

export HEALOS_API_KEY="hlsk_..."
export HEALOS="https://api.healos.ai/ext-api/v1"

Steps

Check which organization the key acts in

curl "$HEALOS/me" -H "X-API-Key: $HEALOS_API_KEY"

Expect 200 with data.org.name set to your test organization and the four scopes above. If it names your live organization, stop and create a key in the test organization instead.

Create a fake patient

curl -X POST "$HEALOS/patients" \
  -H "X-API-Key: $HEALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Testy",
    "last_name": "Quickstart",
    "date_of_birth": "1970-01-01",
    "phone": "+12025550123",
    "external_id": "quickstart-001"
  }'

Expect 201 with the new patient in data. Copy data.id (a numeric string) into PATIENT_ID:

export PATIENT_ID="<data.id from the response>"

Running this again returns 409 with existing.id, because external_id must be unique in the organization. Use that id.

Find the patient by your own id

curl "$HEALOS/patients?external_id=quickstart-001" -H "X-API-Key: $HEALOS_API_KEY"

Expect 200 with a one-item data array. This is how you look up records without storing HealOS ids.

Generate a note from text

curl -X POST "$HEALOS/notes/from-text" \
  -H "X-API-Key: $HEALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"patient_id\": \"$PATIENT_ID\",
    \"text\": \"Test visit with made-up details. Knee pain for two weeks, worse on stairs. No swelling. Plan: physiotherapy, follow up in 4 weeks.\"
  }"

Expect 202 with data.session_id and data.status: "queued". Copy the session id:

export SESSION_ID="<data.session_id from the response>"

Read the note

curl "$HEALOS/sessions/$SESSION_ID/notes" -H "X-API-Key: $HEALOS_API_KEY"

Expect 200. data.notes is empty while the note is being written and holds the note within about a minute. Repeat the call every 10 seconds until it appears. In production, use a NOTE_CREATED webhook instead of polling.

Clean up

curl -X DELETE "$HEALOS/patients/$PATIENT_ID" -H "X-API-Key: $HEALOS_API_KEY"

Expect 200 with { "success": true }. This permanently deletes the fake patient with its session and note.

Expected outcomes

Step	Expected result	If you see something else
1. `GET /me`	`200`, your test organization	`401`: the key is wrong, expired or revoked
2. Create patient	`201`	`409`: already created; use `existing.id`. `403`: the key lacks `patients:write`
3. Look up by `external_id`	`200`, one patient	`404`: the `external_id` doesn’t match
4. Generate note	`202`, `status: "queued"`	`402`: no Scribe sessions left. `409`: a request for this patient is being submitted right now. Don’t resend after a `202`; each call creates a new note
5. Read note	`200`, one note after about a minute	Empty `notes` for over 5 minutes: contact support with the `session_id`
6. Delete patient	`200`, `success: true`	`404`: already deleted

The same flow as a script

The same six calls in JavaScript and Python. Both read the key from the HEALOS_API_KEY environment variable and use only made-up data.

JavaScript: save as quickstart.mjs and run it with Node.js 18 or later: HEALOS_API_KEY=hlsk_... node quickstart.mjs.
Python: install requests (pip install requests), save as quickstart.py and run it with Python 3.8 or later: HEALOS_API_KEY=hlsk_... python quickstart.py.

const BASE = "https://api.healos.ai/ext-api/v1";
const headers = {
  "X-API-Key": process.env.HEALOS_API_KEY,
  "Content-Type": "application/json",
};

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok && res.status !== 409) {
    throw new Error(`${method} ${path} -> ${res.status}: ${json.error}`);
  }
  return { status: res.status, json };
}

const me = await call("GET", "/me");
console.log("Organization:", me.json.data.org.name);

const created = await call("POST", "/patients", {
  first_name: "Testy",
  last_name: "Quickstart",
  date_of_birth: "1970-01-01",
  external_id: "quickstart-001",
});
const patientId =
  created.status === 409 ? created.json.existing.id : created.json.data.id;

const queued = await call("POST", "/notes/from-text", {
  patient_id: patientId,
  text: "Test visit with made-up details. Knee pain for two weeks. Plan: physiotherapy.",
});
const sessionId = queued.json.data.session_id;

let notes = [];
for (let i = 0; i < 30 && notes.length === 0; i++) {
  await new Promise((r) => setTimeout(r, 10_000));
  notes = (await call("GET", `/sessions/${sessionId}/notes`)).json.data.notes;
}
console.log(notes.length ? notes[0].content : "Note not ready yet");

await call("DELETE", `/patients/${patientId}`);
console.log("Deleted the test patient.");

import os
import time

import requests

BASE = "https://api.healos.ai/ext-api/v1"
http = requests.Session()
http.headers["X-API-Key"] = os.environ["HEALOS_API_KEY"]


def call(method, path, body=None):
    res = http.request(method, BASE + path, json=body, timeout=30)
    data = res.json()
    if not res.ok and res.status_code != 409:
        raise RuntimeError(f"{method} {path} -> {res.status_code}: {data.get('error')}")
    return res.status_code, data


_, me = call("GET", "/me")
print("Organization:", me["data"]["org"]["name"])

status, created = call("POST", "/patients", {
    "first_name": "Testy",
    "last_name": "Quickstart",
    "date_of_birth": "1970-01-01",
    "external_id": "quickstart-001",
})
patient_id = created["existing"]["id"] if status == 409 else created["data"]["id"]

_, queued = call("POST", "/notes/from-text", {
    "patient_id": patient_id,
    "text": "Test visit with made-up details. Knee pain for two weeks. Plan: physiotherapy.",
})
session_id = queued["data"]["session_id"]

notes = []
for _ in range(30):
    time.sleep(10)
    _, body = call("GET", f"/sessions/{session_id}/notes")
    notes = body["data"]["notes"]
    if notes:
        break
print(notes[0]["content"] if notes else "Note not ready yet")

call("DELETE", f"/patients/{patient_id}")
print("Deleted the test patient.")

Both scripts send the note request once and never retry it: each call to POST /notes/from-text creates a new note and uses a Scribe session. See Going to production for safe retries.

Next steps

Recipes

Complete tasks, step by step.

Making requests

Pagination, external_id and responses.

Error catalog

Every status and what to do.

Get Started

Recipes

Product Guides

Connections

EHR Integrations

Trust

Go Live

Before you start

Steps

Expected outcomes

The same flow as a script

Next steps

Recipes

Making requests

Error catalog

​Before you start

​Steps

​Expected outcomes

​The same flow as a script

​Next steps

Recipes

Making requests

Error catalog

Before you start

Steps

Expected outcomes

The same flow as a script

Next steps