# Launch encounters

Call these endpoints from your backend when the provider clicks the Nabla button on the EHR encounter screen. Nabla matches (or provisions) the provider, creates or updates the encounter, and returns a URL your frontend should navigate to.

Navigating to that URL logs the provider into Nabla and opens the app on this encounter.

warning

The URL can only be used **once** and expires in **10 minutes**. Do not store it. Request a fresh URL each time the provider opens Nabla.

Authenticate with a [server access token](/connect/guides/authentication.md). Request and response schemas are in the [API reference](/connect/reference/create-or-update-encounters.md).

## Create or update an encounter[​](#create-or-update-an-encounter "Direct link to Create or update an encounter")

**Method:** `POST`

**Path:** [`<baseUrl>/encounters`](/connect/reference/create-or-update-encounters.md)

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

Nabla will:

1. Match the user for your provider (provisioning them if they don't exist yet).
2. Create or update the encounter identified by `external_encounter_id`.
3. Return `{ "encounter_url": string }`.

If an existing user is linked to that `external_provider_id`, `provider_email` must match the email on file.

Pass patient context in `structured_context`, including `patient_demographics`.

Optionally include `unstructured_context` which is free text that will be used when generating the note. Longer `unstructured_context` will make note generation slower, so use it wisely and prefer `structured_context` when possible.

To reopen the same encounter later, either call this endpoint again with the same `external_encounter_id`, or use [Refresh the encounter URL](#refresh-the-encounter-url).

<!-- -->

## Refresh the encounter URL[​](#refresh-the-encounter-url "Direct link to Refresh the encounter URL")

**Method:** `POST`

**Path:** [`<baseUrl>/encounters/url`](/connect/reference/generate-encounters-url.md)

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

Use this when you already have an encounter and only need a new one-time URL. Body: `external_provider_id` and `external_encounter_id`. Response: `{ "encounter_url": string }`.

## Embed Nabla in an iframe[​](#embed-nabla-in-an-iframe "Direct link to Embed Nabla in an iframe")

If you embed the Nabla app in an iframe, set:

```
<iframe src="https://connect.nabla.com/..." allow="microphone; clipboard-write"></iframe>
```

* `microphone` (required) — recording
* `clipboard-write` (required) — copy buttons
* `loopback-network` (optional) — local network access if you use Nabla Echo for audio capture