Overview

Introduction

Flow overview

Requirements

Versionning

Authentication

Server authentication

Incoming APIs

Overview

Provision user

Create encounter

Refresh encounter URL

Outgoing APIs

Overview

Callback authentication (HMAC)

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-02-13 (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": string,
      "pronouns": string | null
    }
  },
  "unstructured_context": string | null
}

Legacy format

• Legacy payload schema

Response

{ "encounter_url": string }