> ## Documentation Index > Fetch the complete documentation index at: https://docs.hi-doctor.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Connect the Hi Doctor MCP connector at https://mcp.hi-doctor.ai/mcp. Add this URL as a remote HTTP MCP server in your client, then sign in and authorise access through OAuth. Setup: https://docs.hi-doctor.ai/mcp/connect. > > The REST API base is https://api.hi-doctor.ai. Hi Doctor Docs at https://docs.hi-doctor.ai/mcp searches documentation; connect to the product endpoint above for patient tools. > > Hi Doctor operates across the whole European Union: residents of all 27 EU member states can use the service, and every consultation is reviewed by an EU-licensed doctor. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only. No algorithm, assistant or API call approves a consultation, issues a prescription or changes a dose. The service is available in eight languages: English, Spanish, German, Dutch, Italian, French, Portuguese and Chinese. > > ## Rules an assistant must follow > > - Never invent, assume or infer a medical answer. "I don't know" is a real answer: ask the patient to pick the closest option rather than guessing for them. > - Never give medical advice and never suggest a medication or a dose. An EU-licensed doctor decides those. > - If a questionnaire returns `ineligible`, say so plainly. Do not retry with altered answers. > - Before anything that costs money or cancels a plan, state exactly what will happen and get an explicit yes. > - Cancellation takes effect at the **end of the paid period**, not immediately. Say so. > - An early order is irreversible: it creates the renewal consultation immediately and uses up the period's one early order. Explain that and get an explicit yes. > - Prescription and invoice links are medical documents. A `signed_redirect` link opens without signing in: give it only to the patient, never repeat it anywhere shared. > - Send option `value`s, not the labels shown to the patient. Labels are translated, values are stable. > - Never ask for card details. Payment happens on Stripe's hosted checkout via a link. > - On severe or sudden symptoms (chest pain, difficulty breathing, severe allergic reaction, suicidal thoughts), stop and direct the patient to their local emergency number. # Partner API consultation lifecycle and statuses > Statuses of a Hi Doctor partner consultation, the consultation resource field by field, versions, decisions and when you can cancel. A partner consultation moves through six public statuses, from `submitted` to a final `approved`, `rejected` or `cancelled`. The consultation resource carries the status, a version number that orders every change, the doctor's decision and any prescriptions. You can cancel a consultation only while no doctor has opened it, so read `cancellable` before offering a cancel button. Last reviewed: 2026-11-04 You create the consultation with [Submit a consultation](https://docs.hi-doctor.ai/partners/submit-a-consultation.md) and learn about each change through [webhooks](https://docs.hi-doctor.ai/partners/webhooks.md). ## What statuses can a consultation have? `submitted` → `in_review` ⇄ `info_requested` → `approved` or `rejected`. A consultation can also be `cancelled` while it is still `submitted`. | Status | Meaning | Terminal | | - | - | - | | `submitted` | Accepted by Hi Doctor, not yet opened by a doctor. | no | | `in_review` | A doctor has opened it. | no | | `info_requested` | The doctor needs structured information from you. | no | | `approved` | The doctor approved treatment. | yes | | `rejected` | The doctor declined treatment. | yes | | `cancelled` | You cancelled it before any doctor opened it. | yes | There is no `completed` status. After approval, track prescriptions in `prescriptions[]`, each with its own status. The diagram is on [How it works](https://docs.hi-doctor.ai/partners/how-it-works.md#status-lifecycle). ## Read a consultation * `GET /v1/partner/consultations/{id}` returns one consultation. * `GET /v1/partner/consultations` lists them, newest first, with the filters `status`, `external_patient_id`, `external_reference`, `created_after`, `created_before` (ISO 8601) and [cursor pagination](https://docs.hi-doctor.ai/partners/pagination.md). Scope: `consultations:read`. ```json theme={null} { "id": "6b1c9a52-2f0d-4e8e-9d1e-7a4c0b2e5f10", "object": "consultation", "mode": "live", "status": "approved", "version": 4, "status_history": [ { "status": "submitted", "version": 1, "at": "2026-11-03T10:15:02Z" }, { "status": "in_review", "version": 2, "at": "2026-11-04T09:02:40Z" }, { "status": "approved", "version": 3, "at": "2026-11-05T14:20:13Z" } ], "external_reference": "ORDER-8812", "product": { "product_id": "", "name": "" }, "country": "NL", "plan_key": "", "dosage": "", "patient": { "id": "0d6f3c1e-91a4-4b8a-b0f7-3c5e2a9d8e41", "external_patient_id": "u_123" }, "submitted_at": "2026-11-03T10:15:02Z", "updated_at": "2026-11-05T14:24:51Z", "reviewer": { "description": "Hi Doctor EU-licensed doctor", "licence_country": "NL" }, "decision": { "outcome": "approved", "reason_category": null, "decided_at": "2026-11-05T14:20:13Z" }, "open_info_request": null, "prescriptions": [ { "id": "3e9d2b7a-5c41-4f08-8a6e-1b2c3d4e5f60", "consultation_id": "6b1c9a52-2f0d-4e8e-9d1e-7a4c0b2e5f10", "status": "issued", "active": true } ], "billing": { "state": "billable" }, "cancellable": false } ``` The prescription entry and `billing` above are shortened: `billing` also carries `price`, and the full prescription shape is on [Prescriptions](https://docs.hi-doctor.ai/partners/prescriptions.md). The timestamps are illustrative and say nothing about how long a review takes. | Field | Meaning | | - | - | | `version` | Increases with every change to the consultation's public state: every field of this object except `version`, `status_history`, `updated_at` and `product.name`. A product rename is catalogue copy and does not advance it. Events carry the same number. Use it to order events. See [Webhooks](https://docs.hi-doctor.ai/partners/webhooks.md#ordering-keep-the-highest-version). | | `status_history` | Every status change with the version it happened at. A prescription change raises `version` without adding an entry: in the example, version 4 is the prescription issued after the approval at version 3. | | `reviewer` | `null` until a doctor opens the consultation. Then an object with a fixed `description` and `licence_country`: the ISO 3166-1 alpha-2 code of the country whose licence covers the doctor's review of this consultation, or `null` while no verified licence record for that country is on file. It never holds a name or licence number. In test mode it is filled with the consultation's own country as soon as the consultation leaves `submitted`, except when it is cancelled: a cancelled test consultation keeps `null`. | | `decision` | `null` until the doctor decides. `outcome` is `approved` or `rejected`. | | `decision.reason_category` | For `rejected` only: `not_eligible` or `safety`. A fixed category, never the doctor's note. Otherwise `null`. | | `open_info_request` | The open information request (`id`, `reason_code`, `requested_at`), or `null`. | | `prescriptions` | The consultation's published prescriptions, including cancelled ones. A replacement prescription that Hi Doctor is still holding back is not listed until it is published. | | `billing.state` | `pending` after submission, `billable` once the doctor has decided (approved or rejected), `void` if cancelled. `billing.price` carries the agreed price. | | `cancellable` | `true` exactly when a cancel would succeed at the time of the read: it applies the same rule as the cancel request (see below). | ## Cancel a consultation `POST /v1/partner/consultations/{id}/cancel`. Scope: `consultations:write`. No body. A consultation can be cancelled **only before a doctor opens it**. Precisely, all of these must hold: * its status is `submitted`; * no doctor has ever opened it, even if it was later reassigned; * it has no decision and no prescription; * no prescription is being issued, signed or replaced. Otherwise the request fails with `409 not_cancellable`. `cancellable` reports exactly this rule, so use it to decide whether to offer a cancel button. The state can still change between your read and your cancel: a cancel can race a doctor opening the case, one of them wins, and if the doctor wins you get `409 not_cancellable`. Handle it by reading the consultation again. If the case is briefly busy you can get `409 consultation_busy`; retry after a short pause. A successful cancel returns the consultation with `status: "cancelled"` and `billing.state: "void"`, and emits `consultation.cancelled`. A cancelled consultation is never billed. Cancel errors are listed in [Partner API errors](https://docs.hi-doctor.ai/partners/errors.md#consultations-information-requests-and-test-mode). ## Frequently asked questions ### How long does a doctor take to review a consultation? The API does not promise a review time. Subscribe to [webhooks](https://docs.hi-doctor.ai/partners/webhooks.md) and update your interface when the status changes. ### Is there a completed status? No. A consultation ends as approved, rejected or cancelled. After approval, follow each prescription in the consultation's prescriptions list. ### Can I cancel a consultation after a doctor has opened it? No. A cancel succeeds only while the consultation is submitted and no doctor has ever opened it. Otherwise the cancel request is refused, and the cancellable field tells you this in advance. ### Is a cancelled consultation billed? No. A successful cancel sets the billing state to void, and a cancelled consultation is never billed. ### Does the reviewer object identify the doctor? No. It holds a fixed description and the licence country only, never a name or a licence number. ### Why did the version increase without a status change? The version number increases with every change to the consultation's public state, such as a prescription being issued after approval. Use it to order events. ### What do I learn when a consultation is rejected? The decision carries a reason category, either not\_eligible or safety. It is a fixed category and never the doctor's note. ## Next steps > [card] [Prescriptions](https://docs.hi-doctor.ai/partners/prescriptions.md) > > The structured prescription data reported after approval. > [card] [Information requests](https://docs.hi-doctor.ai/partners/information-requests.md) > > Answer the doctor when a consultation moves to info\_requested. > [card] [Webhooks](https://docs.hi-doctor.ai/partners/webhooks.md) > > Receive every status change as a signed event. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.