Overview

Introduction

Flow overview

Requirements

Versioning

Authentication

Server authentication

Incoming APIs

Overview

Provision user

Create encounter

Open existing encounter

Open settings

Manage user status

Outgoing APIs

Overview

Callback authentication

Response protocol

Callback types

Reference

Changelog

This endpoint should be called by your backend when the provider clicks the Nabla button in the EHR encounter screen.

Method: POST

Path: <baseUrl>/encounters

POST /encounter is a deprecated alias with the same behavior.

Nabla will:

  1. Match the user corresponding to your provider (provisioning them if they don't exist yet)
  2. Create the encounter
  3. Return a one-time URL your frontend should navigate to

Navigating to this URL will log in the provider into Nabla automatically and open the app on this encounter.

⚠️ The URL can only be used once and expires in 10 minutes. The URL must not be stored.

👤 With provider_email, Nabla will provision the user if they don't already exist. The request will fail if the external_provider_id of an existing user doesn't match the given provider_email.

The external_encounter_id identifies the encounter. To get a fresh URL for the same encounter, either pass the same external_encounter_id to this endpoint or use POST /encounters/url (deprecated alias: POST /encounter/url).

Request payload

Version 2026-09-15 (current)

{
  "provider_email": string,
  "external_patient_id": string,
  "external_provider_id": string,
  "external_encounter_id": string,
  "structured_context": {
    "patient_demographics": {
      "name": string,
      "birth_date": string,
      "gender": "MALE | FEMALE | OTHER | UNKNOWN",
      "pronouns": "HE_HIM | SHE_HER | THEY_THEM" | null
    },
    "visit_diagnoses": [
      {
        "system": "<http://hl7.org/fhir/sid/icd-10-cm>",
        "code": string,
        "display": string
      }
    ] | null
  },
  "unstructured_context": string | null,
  "external_metadata": { [key: string]: string } | null,
  "template_id": string | null
}
Parameter Type Required Description
provider_email string yes Provider email from your EHR
external_provider_id string yes External ID from your EHR
external_patient_id string yes External ID from your EHR
external_encounter_id string yes External ID from your EHR
structured_context object yes Structured contextual used to generate the note
unstructured_context string (max 10000 chars) no Unstructured context (e.g. name, gender, age, pronouns, medical history). Note generation takes longer with a long unstructured_context.
external_metadata object (max 50 keys) no Opaque string key-value map from your EHR (for example a stay identifier). Stored encrypted and echoed back unchanged on export callbacks; not used for note generation. Keys max 40 chars, values max 500 chars. Omit to leave existing metadata unchanged, send {} to clear it.
template_id string (uuid) no Preselects the note template for this encounter. Omit to leave the encounter's current template unchanged.

Selecting a template

The template_id can be found on the Templates tab of Nabla Admin (contact Nabla to enable template admin for your organization).

Select the template and use Copy template ID under Title, or copy the encounterProfileUuid query parameter from the URL. Omit to leave the encounter's current template unchanged.

Version 2026-04-24

Version 2026-02-13

Legacy format

Response

{ "encounter_url": string }