Noa Notes Integration (v1)

Authenticates a client and returns an access token.

A client is a service that wants to use the Noa Notes API.

Retrieves information about the currently authenticated consumer.

Creates a new session.

In this endpoint, episodeId and doctorId are IDs coming directly from your software. We consider them as external IDs on our side.

If a session already exists for the given episodeId, doctorId, and facilityId tuple, the most advanced one is returned: an in-progress or Verified session takes precedence over a New one, and a brand-new session is created only when neither exists. It can allow you to resume a session UI-wise in the widget. When resuming a non-final session, if template in the request body differs from the stored session template, the session template is updated to match the request.

Retrieves the sessions for a facilityId that are not yet in a final status and were started within the last 2 hours. The 2-hour bound exists because a session that a client never cleanly closed (e.g. a crash) is otherwise indistinguishable from one still recording.

startedAt is UTC, without an offset — the same as every other timestamp in this API.

status is the session's current status. Only non-final statuses appear here: Verified, EmptySummaryVerified, Failed and Expired are filtered out, so a failed session never occupies a slot in this list. Interrupted is the one to act on — the client went away (closed tab, lost connection), and the session can be resumed by calling Create Session again with the same episodeId, doctorId and facilityId.

Retrieves the summary of a specific session. Returned data contains the content of the summary and information if a doctor approved its content in the Edit/Confirm Summary page.

Generates a new summary for a session from the transcript already held by Noa, optionally with a different template.

Only possible while the doctor has not verified the summary yet — a verified note is a finished document and is never replaced through this endpoint. Omitting template regenerates with the template the session already has.

The call only starts the regeneration and returns 202; the new summary arrives over the session webhook, and the doctor has to verify it again before it can be read back through Get Session Summary.

Retrieves information about a specific session.

Retrieves the status of a specific session.

This endpoint might be used proactively by the client to check statuses of a given session. An alternative scenario is for the client to expose a webhook that will be used by the Noa Notes Integration API to notify about status changes of the sessions.

Retrieves the verified summary of the session the supplied session token was issued for.

The response is identical to GET /api/v1/consumers/{sessionId}/summary: content is returned only once the doctor has approved the summary on the Edit/Confirm Summary page, and is null until then, while isVerified always reports whether the approval happened.

A session token grants access to exactly one session. Requesting any other session id returns 403, whether or not that session exists.

Attaches analytics context from the calling application to a session, so that product analytics raised by the embedded Noa Notes clients can be correlated with your own.

Call it once the session exists and before the doctor starts recording — typically right after Create Session, when the Recorder is opened. The stored context is read when Noa Notes reports on the session (recording started, processing started, recording finished, note generated, note sent) and is cached from the first of those events onwards, so a later update is not guaranteed to reach the events that follow it.

The call is an upsert: a session holds at most one analytics context and each call replaces the previous one in full, including the fields left out of the request. Every field is optional; analyticsSessionId, analyticsDeviceId and analyticsUserId are what stitch the events to the analytics session, device and user of your own application, while the page fields, dpSource and clientPlatform describe where the Recorder was opened from. Values that do not match the Docplanner tracking taxonomy are not rejected — they fall back to the Noa Notes defaults documented on each field.

Keep string values within the documented lengths, and note that the session is addressed by the session token issued with it: requesting any other session id returns 403 Forbidden, whether or not that session exists, and an unknown session returns 404 Not Found. A successful call answers 200 OK with an empty body.

This endpoint is only available to consumers for whom unified tracking has been enabled by the Docplanner team. For all other consumers it returns 404 Not Found.

Allows the doctor to add a rating and an optional comment to the summary of a specific session.

Allows the doctor to update session details such as training consent

Returns information about the feedback and training consent configuration of a specific session.

Returns the Noa Notes Recorder URL for an existing session, as a JSON string. Open it in a browser or embed it in your application to let the doctor record the appointment; the result is then retrieved with Get Verified Session Summary.

The URL points at the Recorder sign-in page and carries a freshly issued access token, so treat it as a credential: anyone holding the link can open that recording until the token expires. The token is time-limited rather than single-use, and the expiry is configured per environment.

Each call creates a new appointment behind the session and points the session at it, which is why the URL should be requested once, when the doctor is about to record. Calling it again replaces the appointment the session refers to, so a recording made through an earlier URL is no longer the one the session resolves to.

Failures are reported as 400 Bad Request with a plain-text Error processing token: ... message — including the case where the session the token was issued for no longer exists, and the case where the appointment could not be created. The session token grants access to exactly one session: requesting any other session id returns 403 Forbidden, whether or not that session exists.

Returns every doctor currently registered for the given facility, as a JSON array.

Each entry reports the doctor's name, the externalDoctorId from your own system and whether the embedded Noa Notes widget is enabled for them. Doctors removed with Remove Facility Doctor are left out, and a facility with no doctors returns an empty array.

A facility that does not exist returns 404 Not Found, and one that belongs to another consumer returns 403 Forbidden.

Registers a doctor for the given facility and returns the registered doctor with 201 Created.

externalDoctorId is the identifier of the doctor in your own system and must be unique within the facility. Registering an identifier that is already registered returns 409 Conflict. Registering one that was removed earlier restores that doctor instead of creating a second one: it keeps its Noa Notes id and its previous isWidgetEnabled setting, and takes the name from this request.

isWidgetEnabled decides whether the doctor may use the embedded Noa Notes widget. It applies when the doctor is created and is ignored when an earlier registration is restored. name and externalDoctorId must both be non-empty.

An unknown facility returns 404 Not Found, and one belonging to another consumer 403 Forbidden.

Updates the display name of a doctor already registered for the facility and returns the updated doctor.

The doctor is identified by the externalDoctorId from your own system, and name is the only thing that changes: the Noa Notes id and isWidgetEnabled are left as they are.

A doctor that was removed can still be renamed this way; it stays out of Get Facility Doctors until it is registered again. 404 Not Found is returned if either the facility or the doctor is unknown, and 403 Forbidden if the facility belongs to another consumer.

Removes a doctor from the facility and answers 204 No Content.

The removal is soft: the doctor stops being listed by Get Facility Doctors and the embedded Noa Notes widget is no longer offered for them, while their Noa Notes id, their widget setting and every session and summary already created for them are kept. Registering the same externalDoctorId again restores that doctor rather than creating a second one, and repeating the removal answers 204 No Content as well.

Sessions are created from the identifiers you supply and are not matched against this registry, so removing a doctor here does not by itself stop sessions being created for that externalDoctorId. Where the widget visibility check is enabled for your consumer, it is the doctor's isWidgetEnabled setting — not their removal — that makes Create Session reject a request carrying a facilityId.

404 Not Found is returned if either the facility or the doctor is unknown, and 403 Forbidden if the facility belongs to another consumer.