Skip to main content

Session workflow

Introduction​

This guide walks through the typical lifecycle of a therapy session in the Application API:

  1. Create a session from a recording or from text notes.
  2. Wait for results via webhooks.
  3. Fetch the session with its notes and other insights.
  4. 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:

  • providerUserId and clientUserId — Upheal userIds, 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 — recordingUrls and recordingContent (Recording for a recorded session, DictatedNotes for 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:

EventMeaningWhat to do
SESSION_PROCESSING_NOTES_COMPLETEDNotes are ready.Fetch the session and read notes.
SESSION_PROCESSING_COMPLETEDEverything is ready — transcript, analytics, and notes.Fetch the session if you need more than notes.
SESSION_PROCESSING_FAILEDProcessing 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, or Error. Done means every requested note has finished.
  • notes — the generated notes, one per note template.
  • transcript — utterances with speaker labels (A, B, …) and the speakerMapping from labels to Upheal user IDs.
  • error — present when state is Error.

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.

FieldWhat it doesRecording sessionText-to-note session
noteTemplateIdsGenerates notes for these templates — new ones are added, existing ones regenerated.yesyes
speakerMappingReassigns transcript speakers to users, e.g. to swap provider and client. Regenerates notes.yes400
inputReplaces the text the session was created from (input.text on create), sent the same way as { "text": "..." }. Regenerates notes.400yes

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.