🎙️ Recording & Summaries

The Recording feature is the core of Noa Notes. It allows doctors to effortlessly capture the conversation during a patient consultation, which is then transformed by Noa Notes’ AI into a structured, editable medical summary.

This section explains how to start and manage a recording, track its lifecycle, and retrieve finalized summaries via the API.

🧭 General Overview

• Every recording is tied to a unique session, created via the Note Notes Integration API.
• The Noa Notes Recorder runs in the browser and securely captures the conversation.
• When the doctor finishes recording, Noa Notes' backend generates a structured summary. The user is redirected to the Edit/Verify Summary page.
• The summary can be retrieved via Note Notes Integration API once it is verified.

▶️ How Recording is Started and Stopped

• Start: The doctor opens the recorderUrl received from the session response and clicks the "Start" button.
• Stop: The recording is manually stopped by the doctor in the Noa Notes Recorder UI.

⚠️ You do not need to stop the recording via API—this is handled fully within the UI.

🔁 Recording Flow

This step-by-step example outlines the full recording lifecycle:

1. Create a Session

Send a request to initialize a session.

curl -X POST https://yourdomain.com/api/v1/consumers/sessions \
-H "Authorization: Bearer {accessToken}" \
-H "Content-Type: application/json" \
-d '{
  "episodeId": "string", // *Required
  "doctorId": "string", // *Required
  "webhookUrl": "string",
  "template": "string",
  "visitType": "FirstVisit|FollowUpVisit",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "facilityId": "string",
  "language": "string",
  "speciality": {
    "value": "string"
  }
}'

2. Open Recorder & Validate Summary

After receiving the recorderUrl from the session creation response:

• Render the Noa Widget inside your application
• The doctor:
  • Starts recording by using Start Noa Notes button inside the Noa Widget
  • Records the appointment
  • Edits and validates the summary on the Edit/Validate Summary page

3. Check Session Status

To receive session status updates, we offer webhooks. You define the webhook when calling the create session endpoint: POST /api/v1/sessions. Consult the API documentation for more details.

{
  "webhookUrl": "string"
}

The following status will be returned:

Webhook Status updates

The webhook URL can either be specified during each new session creation or provided to our integration team to set it as the default. Once configured, it will deliver session status updates automatically.

For more details about session statuses, see Session statuses

Webhook response example

{
  "sessionId": "abd6b43d-81ce-49e7-b566-f87bc33372e9",
  "episodeId": "episodeXYZ",
  "facilityId": "facilityXYZ",
  "doctorId": "doctorXYZ",
  "status": "Summarized",
  "error": null
}

Additionally, you can check the status of the season using the folding endpoint.

Use the session ID to monitor the current state of the session:

GET /api/v1/sessions/{sessionId}/status
Authorization: Bearer {sessionToken}

4. Retrieve Summary

GET /api/v1/consumers/{sessionId}/summary

Authorization: Bearer {sessionToken}

Example of Summary Response

{
  "id": "abc-123",
  "sessionId": "xyz-456",
  "content": "{
    \"Personal Information\":\"<ul><li><p><strong>Age: </strong>30 years old</p></li></ul>\",\"Reason for the Visit\":\"<ul><li><p><strong>Primary Problem: </strong>Leg injury</p></li><li><p><strong>Symptoms: </strong>Pain in the leg</p></li><li><p><strong>Cause: </strong>Kick received during soccer game one week ago</p></li><li><p><strong>Current Condition: </strong>Can walk relatively well, probable inflammation</p></li></ul>\",\"Conclusion\":\"<ul><li><p><strong>Recommended Actions: </strong></p><ul><li><p>Recommend scans to assess the condition</p></li><li><p>Prescribe anti-inflammatory medication</p></li></ul></li></ul>\"
  }",
  "isVerified": true,
  "createdAt": "2025-05-08T14:33:00Z",
  "verifiedAt": "2025-05-08T14:35:12Z"
}

The "content" field is a JSON string with sections as keys and their HTML-formatted clinical notes as values, using lists and paragraphs for clear, structured display. In the case of empty summary because of the lack of transcript, the "content" field is null.

5. Information about empty summary

It might happen that the summary is empty because:

• no audio was recorded to generate a transcript
• the transcript didn't contain enough medical information to create a proper summary
• an unexpected issue happened (eg. connection disruption)

In such cases, the status of the session becomes EmptySummaryVerified. This status represents the absence of summary, is a final status, and is automatically toggled to by the system after the Summarized status. The summary content will not be filled-in and will be null.

In order to display it properly in your system, you can check if the status is EmptySummaryVerified.

📝 How to use Templates

You can use templates to define under which format the summaries should be generated.
A template is an object / JSON containing Key/Value pairs.

Keys are used to define a section that should be in the summary, while Values are a description of the section.
Values can be empty, and you can add an arbitrary amount of Keys.
The description written in Values will help Noa to understand what you would like to see appearing in which section.

Here is an example of valid template:

{
  { "Personal Information", "Include patient demographics and insurance information" },
  { "Reason for the Visit", "Detailed description of the presenting problem" }
}

As described above, it is also valid to have empty values:

{
  { "Personal Information", null },
  { "Reason for the Visit", "Detailed description of the presenting problem" }
}

Please find more information about templates usage in our endpoints in the API docs.