Session workflow
Introduction
This guide walks through the typical lifecycle of a therapy session in the Application API:
- Create a session from a recording or from text notes.
- Wait for results via webhooks.
- Fetch the session with its notes and other insights.
- Update the session if something needs to change.
Where to start
- You create sessions through the API — your system sends Upheal the recording or the provider's notes. Start at 1. Create a session.
- Providers capture sessions directly in Upheal — for example with the audio recorder, telehealth, the mobile or desktop apps, or the browser extension — and your system only consumes the notes. Start at 2. Wait for results.
Steps 2–4 are the same for both. Session webhooks fire for every session in your organization, however it was captured.
1. Create a session
The provider and client must already exist in Upheal — see Sync users. You also need the IDs of the note templates to generate — list them with GET /api/v1/note-templates.
Call POST /api/v2/therapy-session with:
providerUserIdandclientUserId— UphealuserIds, not your own IDs. The provider must have access to the client.noteTemplateIds— the note templates to generate notes from.input— exactly one of:recording—recordingUrlsandrecordingContent(Recordingfor a recorded session,DictatedNotesfor a dictated summary).text— the provider's written notes as{ "text": "..." }(a text-to-note session).
The response contains the new sessionId. Pass partnerAppointmentId (your ID for the appointment) as well — Upheal includes it in every session webhook, so events are easy to match to your records. See the endpoint reference for the other optional fields.
Uploading a recording. Get a pre-signed URL from GET /api/v1/recording-url, PUT the file there, and pass that URL in recordingUrls.
Sessions without a client record. For anonymous sessions, omit clientUserId and optionally pass clientPronouns (MasculineHim, FeminineHer, or NeutralThem) so the notes refer to the client correctly. The two fields can't be used together.
2. Wait for results
Processing runs asynchronously. Don't poll the session — subscribe to session webhooks and fetch the session when the relevant event arrives:
| Event | Meaning | What to do |
|---|---|---|
SESSION_PROCESSING_NOTES_COMPLETED | Notes are ready. | Fetch the session and read notes. |
SESSION_PROCESSING_COMPLETED | Everything is ready — transcript, analytics, and notes. | Fetch the session if you need more than notes. |
SESSION_PROCESSING_FAILED | Processing stopped because of an error. | Fetch the session and read error. |
Most integrations only need the notes, as fast as possible, so they act on SESSION_PROCESSING_NOTES_COMPLETED. It usually arrives at about the same time as SESSION_PROCESSING_COMPLETED, but that is not guaranteed.
SESSION_PROCESSING_NOTES_COMPLETED is sent each time a note finishes. A session with two note templates sends it twice, and it is sent again whenever an update regenerates the notes. To know that all notes are ready, check that the fetched session's state is Done. SESSION_PROCESSING_COMPLETED is sent when the session is first ready, and again each time Upheal successfully transcribes the session again and rewrites its notes.
SESSION_PROCESSING_FAILED doesn't say what went wrong. Fetch the session — its error object has a code and a human-readable message. See Error codes.
3. Fetch the session
Call GET /api/v2/therapy-session/{sessionId}. Key fields:
state—InProgress,Processing,Done, orError.Donemeans every requested note has finished.notes— the generated notes, one per note template.transcript— utterances with speaker labels (A,B, …) and thespeakerMappingfrom labels to Upheal user IDs.error— present whenstateisError.
4. Update a session
All changes go through PATCH /api/v2/therapy-session/{sessionId}. Send only the fields you want to change; at least one is required. The response is the updated session.
| Field | What it does | Recording session | Text-to-note session |
|---|---|---|---|
noteTemplateIds | Generates notes for these templates — new ones are added, existing ones regenerated. | yes | yes |
speakerMapping | Reassigns transcript speakers to users, e.g. to swap provider and client. Regenerates notes. | yes | 400 |
input | Replaces the text the session was created from (input.text on create), sent the same way as { "text": "..." }. Regenerates notes. | 400 | yes |
To swap speakers, send the session's transcript.speakerMapping back with the user IDs switched:
{
"speakerMapping": {
"A": "<client userId>",
"B": "<provider userId>"
}
}
Updates return 400 if the session is still processing or in Error, or its transcript was deleted. speakerMapping and input are also rejected if any note was edited manually in Upheal. After a successful update, wait for SESSION_PROCESSING_NOTES_COMPLETED and fetch the session again.