Fundamentals

This section introduces the core technical concepts behind Noa Notes Integration. Understanding these principles will help you build a reliable and production-grade integration between your PMS and Noa Notes.

Integration Architecture Overview

Noa Notes Integration is composed of:

• DocPlanner NOA Notes Integration REST API
• Embeddable NOA Widget (UI)

In addition to the above we offer the following:

• Token-based authentication
• Webhooks for real-time updates The typical flow looks as follows:

NOA Notes Integration Flow

Follow these steps to implement the NOA Notes workflow within your system:

1. Authenticate via API
   Use the provided clientId and secret to authenticate with our API.
   This will return a Bearer token required for accessing the /consumers/* endpoints.

2. Create a Session
   Use the access token to create a new session for the appointment via the /consumers/sessions endpoint.
   This call will return a Session token used for session-scoped operations such as retrieving the summary.

3. Render the NOA Notes Widget
   Embed the NOA Notes widget in your PMS frontend using the session token.
   This enables doctors to interact with the widget during the consultation.

4. Record and Review Consultation
   Allow the doctor to start recording, review the AI-generated transcription, and approve or edit as needed within the widget.

5. Track Session Status via Webhook
   Implement webhook listeners to monitor session status changes (e.g., started, completed, reviewed).

6. Retrieve Summary and Populate EHR
   After session completion, retrieve the AI-generated summary and use the provided data to populate the patient’s EHR using your pre-defined template.

Live Environment – Country-Specific URLs

For live usage with real patients

Country	Locale	Base URL
Poland	pl	https://integration.notes.pl.noa.ai/api/v1/
Germany	de	https://integration.notes.de.noa.ai/api/v1/
Spain	es	https://integration.notes.es.noa.ai/api/v1/
Portugal	pt	https://integration.notes.pt.noa.ai/api/v1/
Czech Republic	cz	https://integration.notes.cz.noa.ai/api/v1/
Türkiye	tr	https://integration.notes.tr.noa.ai/api/v1/
Italy	it	https://integration.notes.it.noa.ai/api/v1/
Argentina	ar	https://integration.notes.ar.noa.ai/api/v1/
Brazil	br	https://integration.notes.br.noa.ai/api/v1/
Chile	cl	https://integration.notes.cl.noa.ai/api/v1/
Colombia	co	https://integration.notes.co.noa.ai/api/v1/
Peru	pe	https://integration.notes.pe.noa.ai/api/v1/
Mexico	mx	https://integration.notes.mx.noa.ai/api/v1/

It is strongly recommended to choose the service located nearest to you.

Consumers

A Consumer is a PMS system registered in Noa Notes. Each Consumer has its own:

• Default Webhook URL for status updates
• Default language of the notes
• Default template for the notes
• Default specialty of a doctor

These defaults are configured by a Docplanner specialist during onboarding.

You can retrieve your current configuration via:

GET /api/v1/consumers/me
Authorization: Bearer {accessToken}

Default values are automatically applied when optional parameters are not provided during session creation.

Sessions

A session represents a single use of Noa Notes and expires after a set time. To get a Noa Notes Recorder URL and widget displayed, the client must first create a session. This URL allows the doctor to access the recorder. After the session, a summary of the appointment is generated and should be used to fill in EHR data in the client app.

Session creation takes only your own doctorId, facilityId and episodeId — no patient identity, apart from the optional patientGender.

Authentication

All API requests must be authorized using an access token obtained via client credentials.

Key Concepts

• Access is restricted to registered PMS clients
• Authentication is stateless (no sessions or cookies)
• All communication must be over HTTPS
• Tokens are short-lived, tied to the Consumer, and not user-specific

How to Get an Access Token

Endpoint: POST /api/v1/auth

Request:

{
  "clientId": "your-client-id",
  "secret": "your-client-secret"
}

Response:

{
  "accessToken": "string",
  "expiry": 3600
}

Use the token in the Authorization header for all protected API calls:

Authorization: Bearer {accessToken}

Which Token to Use

There are two token types in the integration. The URL path alone does not determine which token an endpoint requires — use the table below as the authoritative reference:

Endpoint	Token required
POST /api/v1/auth	none
GET /api/v1/consumers/me	access token
POST /api/v1/consumers/sessions	access token
GET /api/v1/consumers/{sessionId}/summary	session token
GET /api/v1/sessions/{sessionId}/status	access token
GET /api/v1/sessions/{sessionId}	access token

⚠️ A common mistake is using an access token to call GET /consumers/{sessionId}/summary — this returns 403 Forbidden. That endpoint is session-scoped and requires the session token returned by POST /consumers/sessions.

Endpoint Availability

The integration guide documents the endpoints intended for external integrators. Some additional endpoints are visible in the public API reference but are for internal Docplanner use only and should not be called from external systems:

Endpoint	Reason not for external use
PUT /api/v1/sessions/{sessionId}/analytics	Internal analytics telemetry used by the NOA Notes widget
GET /api/v1/sessions/{sessionId}/recorder	Internal recorder retrieval; use the recorderUrl from POST /consumers/sessions instead
GET /api/v1/facility/{externalFacilityId}/doctors	Facility provisioning — not part of the standard integration flow
POST /api/v1/facility/{externalFacilityId}/doctors	Facility provisioning — not part of the standard integration flow
PUT /api/v1/facility/{externalFacilityId}/doctors/{externalDoctorId}	Facility provisioning — not part of the standard integration flow
DELETE /api/v1/facility/{externalFacilityId}/doctors/{externalDoctorId}	Facility provisioning — not part of the standard integration flow

⚠️ Calling these endpoints from an external integration is unsupported and may produce unexpected behavior.

Token Errors

Status	Description
401 Unauthorized	Token is missing or invalid
403 Forbidden	Token is valid but lacks permission

Error Handling

We use standard HTTP status codes:

Status Code	Meaning
200 OK / 201 Created	Request succeeded
400 Bad Request	Missing/invalid request body
401 Unauthorized	Invalid or expired token
403 Forbidden	Valid token, but action not allowed
404 Not Found	Resource doesn't exist
500 Internal Server Error	Server-side error

All responses include descriptive error messages to help diagnose issues.

Fair Usage Policy

To maintain system integrity and prevent abuse, we enforce the following rule:

One Active Session per Doctor

A doctor can only have one active session at a time.

This reflects the real-world workflow: doctor - patient - appointment.

If a second session is created for a doctor while another is still active:

• The API will return the current active session
• The first session must be closed or expire before a new one can begin

Best Practices

• Always track the session status using a webhook or the GET /sessions/{id}/status endpoint
• Prevent your frontend/backend from unintentionally creating duplicate sessions

Monitoring Active Sessions

Lists the sessions currently running in a facility, so you can apply a concurrent-session limit. Noa does not enforce the limit — this endpoint only reports it.

GET /api/v1/consumers/facilities/{facilityId}/sessions/active
Authorization: Bearer {accessToken}

{
  "facilityId": "facility-789",
  "activeSessions": [
    {
      "sessionId": "0f0e023d-2a3a-42cd-9d64-9ed2eb2fbd16",
      "doctorId": "doctor-42226",
      "episodeId": "episode-2222",
      "startedAt": "2026-09-09T08:41:07.482"
    }
  ]
}

A session is listed while it is not in a final status and was created in the last 2 hours — so a consultation running longer than that drops off the list while it is still recording. startedAt is the session's creation time, not when recording began. An unknown facilityId, or one never set on a session, returns 200 OK with an empty array.

Timestamps

All timestamps are UTC with no Z suffix and no offset — 2026-09-09T08:41:07.482. Most date libraries read that as local time, shifting it by your own offset with no error.

new Date(summary.createdAt + "Z"); // ✅ UTC
new Date(summary.createdAt); // ❌ local time

This applies to every timestamp field: createdAt, updatedAt, verifiedAt, closedAt and startedAt. Fractional-second precision varies.