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

<aside> 🆕

Available from version 2026-03-23. see Versioning

</aside>

API version

Call this endpoint from your backend when you want to create or update a provider user without opening an encounter—for example to set specialty and dictation locales before the first launch.

Method: POST

Path: <baseUrl>/users

Send a Bearer server access token on the request. For how to obtain it, follow Server authentication.

Nabla will:

1. Resolve your organization from the OAuth client used to obtain the token
2. Look up a user already linked to the given external_provider_id on your Nabla Connect instance
3. If found, return that user and merge in any settings you provided
4. If not found, create the account and assistant user as needed, link the EHR practitioner, then return the new user

👤 If a user already exists for that external_provider_id, the email you send must be the same as on file. If external_provider_id and provider_email would point at two different existing users, the request fails with 409 Conflict.

ℹ️ settings is optional. Leave it out to keep the current specialty and locales. For a brand-new user, defaults apply until you send settings or the provider completes onboarding.

You can also rely on Create encounter to provision the user the first time; this endpoint is mainly useful when you want those fields set before the button is clicked.

Request payload

{
  "provider_email": string,
  "external_provider_id": string,
  "settings": {
    "specialty": {
      "kind": enum,
      "other_specialty_name": string | null
    } | null,
    "speech_locale": enum,
    "secondary_speech_locale": enum | null
  }
}

• specialty.kind
• speech_locale / secondary_speech_locale

Response

{
  "provider_email": string,
  "external_provider_id": string,
  "settings": {
    "specialty": { "kind": enum, "other_specialty_name": string | null },
    "speech_locale": enum,
    "secondary_speech_locale": enum | null
  } | null,
  "created_at": string // ISO-8601, user creation time
}