> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Practice

> Read patients, appointments, openings, providers and treatment plans, and book appointments behind approval

**Practice management (via NexHealth)** reaches Dentrix, Eaglesoft, Open Dental, Curve, Denticon, athenaOne and eClinicalWorks. **Epic** reaches hospitals and health systems over FHIR R4; see [Epic](#epic).

## Connect

Authorize OneShot in NexHealth. In console **Connections**, choose **Practice management (via NexHealth)**, select your practice system and enter its subdomain and location ID.

Equivalent `POST /v1/connections`:

```json theme={null}
{
  "name": "front-desk",
  "kind": "app",
  "system": "nexhealth",
  "practice_system": "Dentrix",
  "subdomain": "example-practice",
  "location_id": "123"
}
```

To change practices, revoke and start again. HIPAA organizations need `nexhealth` approved under their compliance policy.

## Reads

Every tool takes `connection_id`, `limit` (1 to 100, default 25) and optional `cursor`. Pass `next_cursor` with unchanged filters, including after empty pages. Missing fields are null.

| Tool | POST route | Filters |
| - | - | - |
| `practice_patients` | `/v1/tools/practice/patients` | `query` (name, email, phone), `patient_id`, `updated_since`, `due_for_recall` |
| `practice_appointments` | `/v1/tools/practice/appointments` | `starts_after`, `starts_before`, `patient_id`, `provider_id`, `status` |
| `practice_openings` | `/v1/tools/practice/openings` | `starts_after`, `starts_before`, `provider_id`, `appointment_type_id` |
| `practice_providers` | `/v1/tools/practice/providers` | `query` (name) |
| `practice_treatment_plans` | `/v1/tools/practice/treatment-plans` | `patient_id`, `status`, `updated_since`, `plan_id` |

Both windows are required, positive, ISO 8601 with timezone, start-inclusive and end-exclusive. Appointments allow 31 days; openings allow 14. Completed means checked out, not simply past.

`due_for_recall` means before today in UTC. Pages hold at most one patient. `last_visit` and `next_appointment` are always null; use appointment reads.

## Treatment plans

`updated_at` means plan update time; `start_date`/`end_date` mean procedure dates. `updated_since` is inclusive. `plan_id` retains filters.

```json theme={null}
{
  "treatment_plans": [
    {
      "id": "423",
      "name": null,
      "patient_id": "415",
      "status": "proposed",
      "updated_at": "2026-11-01T00:00:00Z",
      "procedures": [
        {
          "id": "11",
          "code": "D6100",
          "name": "Implant Removal",
          "status": "planned",
          "fee": {
            "amount": "62.00",
            "currency": "USD"
          },
          "provider_id": "83",
          "appointment_id": null,
          "start_date": "2026-10-10",
          "end_date": "2026-10-11"
        }
      ],
      "source": {
        "system": "nexhealth",
        "id": "423"
      }
    }
  ],
  "next_cursor": null
}
```

## Privacy and payment

Read records are inline, untrusted and never saved, including goal results. Logs and receipts contain identifiers and counts only. Foreign, revoked, expired and compliance-refused connections are rejected before payment. Failed paid reads return account credit. See [Pricing](https://docs.oneshotagent.com/pricing.md).

## Book an appointment

`POST /v1/tools/practice/appointments/book` (`practice_appointments_book`) waits for approval unless the agent's policy allows it.

Send `Idempotency-Key` with:

```json theme={null}
{
  "connection_id": "11111111-1111-4111-8111-111111111111",
  "patient_id": "415",
  "provider_id": "83",
  "starts_at": "2026-11-06T09:00:00Z",
  "appointment_type_id": "27"
}
```

Optional `operatory` identifies the room; `note` allows 500 characters. Retry approved requests unchanged with `X-Approval-Id`.

Availability is rechecked before writing. `slot_taken` writes nothing. Repeated keys return the recorded outcome. `write_outcome_unknown` is never retried: check the schedule before booking again.

Returns `{ id, starts_at, ends_at, provider, status, source: { system, id } }`, retained for replay without patient identifiers or note. Booking does not change case state.

## Epic

Your Epic team activates the OneShot backend app and sends you the client id Epic issued for it. OneShot records that activation for your organization; until recorded, a start answers `not_granted`. Then start with that id and your FHIR R4 base URL (https, public host, default port):

```json theme={null}
{
  "name": "scheduling",
  "kind": "app",
  "system": "epic",
  "fhir_base_url": "https://fhir.example.org/api/FHIR/R4",
  "client_id": "<client id>"
}
```

HIPAA organizations need `epic` approved under their compliance policy, after a signed BAA.

Identifiers are FHIR ids. `due_for_recall` answers `unsupported_filter`; `appointment_type_id` takes a code or `system|code`. A booking completes only when Epic answers booked.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.