# Introduction

The **Dr.Online Connected API** is a server-to-server REST API on `/v1/connected/*` (same host as this docs page, under your regional API base).

Your integration is **connected** to Dr.Online: you run the patient-facing experience and payment; we provide **our** appointment types, practitioners, availability, scheduling, and patient records for people you book or register through this API.

* One **catalog per API credential** (Dr.Online catalogue for that key) — not your own uploaded catalogue.
* Typical flow: `GET /connected/account` → discovery GETs → hold → confirm → optional `GET /connected/patients/{patient_id}`.
* Need another catalogue? Request a **separate credential** (no per-request channel header).

## Use cases <a href="#api-1-description-use-cases" id="api-1-description-use-cases"></a>

* **Custom checkout** — Show Dr.Online clinicians and times in your app; charge on your PSP; confirm with `external_payment_reference`.
* **CRM or care navigation** — Book from a case record without our embed widget.
* **Reconciliation** — Poll `GET /connected/appointments` with your `partner_reference` and PSP reference after confirm.
* **Sandbox-first integration** — Build against `sk_sandbox_*`, then switch base URL and live keys.

#### Important concepts <a href="#api-1-description-important-concepts" id="api-1-description-important-concepts"></a>

| Concept                 | Meaning                                                                                                                                                                                                                                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connected catalogue** | What you can offer: `appointment_types`, `practitioners`, `slots` (and `slots/validate`). Fixed for your credential.                                                                                                                                                                                                              |
| **Booking**             | `appointment_holds` → `appointments/.../confirm` → optional `cancel` or `reschedule`. Holds are short-lived locks; confirm creates the real visit.                                                                                                                                                                                |
| **Appointment**         | A booked visit in our system. `start` / `end` are the **current** scheduled UTC instants. After confirm, the `appointment_id` may differ from the hold blocker id — store the id returned from confirm.                                                                                                                           |
| **Patient**             | Write on hold (optional) and confirm (required): `first_name`, `last_name`, `email`, optional `phone`, `sex`, `date_of_birth` (`YYYY-MM-DD`). Read via `GET /connected/patients/{patient_id}` or embedded `patient` on `GET /connected/appointments/{appointment_id}`. No patient search or arbitrary chart access.               |
| **Questionnaire**       | Pre-appointment intake form when required for the appointment type. `GET /connected/appointments/{appointment_id}/questionnaire` or `GET /connected/questionnaires/{questionnaire_id}` — includes `completion_url` for the patient.                                                                                               |
| **Metadata**            | Read-only on catalogue resources. On booking, a single optional `metadata` object on hold create and confirm is stored on the **appointment** (`appointment.metadata` on responses and `GET /connected/appointments/{id}`). Patient write accepts `metadata` on the patient object. Keys cannot start with `dronline` (reserved). |
| **Credential**          | Bearer `sk_live_*` or `sk_sandbox_*` from the one-time reveal flow. Server-to-server only from your backend.                                                                                                                                                                                                                      |

#### Naming & JSON conventions <a href="#api-1-description-naming-json-conventions" id="api-1-description-naming-json-conventions"></a>

* **snake\_case** field names on requests and responses.
* **Resource objects**: every resource has `object` and `id`; lists use `{ object: "list", url, has_more, data }`.
* **Field order** on objects: `id`, `object`, then remaining keys A–Z (for stable docs and diffs).
* **Timestamps**: ISO 8601 UTC strings on `start`, `end`, `confirmed_at`, `cancelled_at`, etc.
* **Money**: `price_in_cents` on `appointment_type` plus `currency` from `GET /connected/account` (minor units).
* **Errors**: `{ error: { type, code, message, param? } }` — branch on `code`; log `X-Request-Id` for support.
* **`booking_channel_id`**: Always `null` on responses (reserved).

#### Authentication <a href="#api-1-description-authentication" id="api-1-description-authentication"></a>

`Authorization: Bearer <secret_key>`. Scope is determined entirely by the credential Dr.Online issued for your integration.

#### Getting started <a href="#api-1-description-getting-started" id="api-1-description-getting-started"></a>

Typical booking sequence (base URL e.g. `https://api.dronline.uk/v1`, paths below are relative to that base):

1. `GET /connected/account` — currency, timezone, feature flags, contract version.
2. `GET /connected/appointment_types` → `GET /connected/practitioners` → `GET /connected/slots` (or `POST /connected/slots/validate`).
3. `POST /connected/appointment_holds` — optional `patient`; save `hold_token` and `appointment_id`.
4. `POST /connected/appointments/{id}/confirm` — required `patient`, `external_payment_reference`, `X-Appointment-Hold-Token`, and `Idempotency-Key`.
5. `GET /connected/appointments` or `GET /connected/appointments/{id}` — reconcile; optional `POST /connected/appointments/{id}/cancel` or `POST /connected/appointments/{id}/reschedule` (same policy as patient self-service: one reschedule, within 48h of original start, not within 24h of start).
6. `GET /connected/patients/{patient_id}` — demographics for patients your integration linked.
7. When applicable, `GET /connected/appointments/{appointment_id}/questionnaire` — intake form status and `completion_url` for the patient.

Use **Try it** on each operation below. Required headers: `Authorization`; after a hold, `X-Appointment-Hold-Token`; on hold create and confirm, `Idempotency-Key` (recommended). Log `X-Request-Id` when contacting Dr.Online support.

OpenAPI JSON: `/api/partner/openapi-partner-v1.json` on the same API host as this page (not under `/v1`).

**Contract version:** `GET /connected/account` returns `api_version` (date) and `path_version` (`v1`). Additive changes may ship without a date bump; breaking path changes use a new prefix or version.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dronline.uk/connected-api/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.