> ## 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 idempotency: retry submissions safely > Retry Hi Doctor Partner API submissions safely with an Idempotency-Key: replayed responses, reuse errors, in-progress requests and the 24-hour lifetime. The `Idempotency-Key` header makes retrying a Hi Doctor Partner API consultation submission safe. Within 24 hours, a retry with the same key, path and body returns the stored result instead of creating a second consultation. `POST /v1/partner/consultations/` requires the header; other write endpoints do not take it. Last reviewed: 2026-11-04 Networks fail: a submission can reach Hi Doctor while the response never reaches you. After 24 hours the stored result is gone and the request runs again (see [Lifetime](#lifetime)). This page covers the Partner API only; the patient REST API has its own [idempotency rules](https://docs.hi-doctor.ai/api-reference/idempotency.md). ## Where does an Idempotency-Key apply? `POST /v1/partner/consultations/` **requires** an `Idempotency-Key` header. Without it the request fails with `400 idempotency_key_required`. Other write endpoints do not take an `Idempotency-Key`, and not all of them are safe to repeat: * A cancel that already succeeded returns `409 not_cancellable` and changes nothing, so it is safe to retry. * Repeating `POST /v1/partner/files/` stores another file with a new `upload_id`. Use only the `upload_id` you put in the submission; the extra upload is never attached. * In test mode, repeating a [test advance](https://docs.hi-doctor.ai/partners/test-mode.md#advance-a-test-consultation) to `prescription_issued` adds another synthetic prescription. ## How do I choose a key? * 8 to 128 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`. Anything else fails with `400 invalid_idempotency_key`. * Use a fresh random value, such as a UUID, or a value tied to your order, such as `order-8812-submit`. * Store the key with the order **before** you send the request, so a retry after a crash uses the same key. * Keys are scoped to your partner, the mode and the operation. Rotating your API key does not affect them. ## What happens on a retry? | You send | You get | | - | - | | A new key | The request runs normally. | | The same key, path and body, after the first request finished | The **stored original response**, same status and same body, with the header `Idempotent-Replayed: true`. Nothing runs again. | | The same key while the first request is still running | `409 idempotency_in_progress`. Wait briefly and retry with the same key. | | The same key with a different body or a different path | `422 idempotency_key_reuse`. Nothing runs. Use a new key for a new request. | The request is compared by its exact path and its whole body (key order and spacing do not matter). The path is compared as sent: `/v1/partner/consultations/` and `/v1/partner/consultations` count as different paths, so retry with the same URL as the first attempt, ideally the form the [Partner API reference](https://docs.hi-doctor.ai/api-reference/connectivity/check-an-api-key.md) lists, with the trailing slash. ## Are errors stored? Only successful submissions are stored. If the first request failed with a `4xx` error, for example `422 invalid_answers`, nothing is stored for the key: fix the request and send it again. You can keep the key or use a new one. If Hi Doctor fails while processing, everything the request started is rolled back together, including the stored key, so a retry with the same key runs cleanly. ## Lifetime Stored results are kept for 24 hours. A retry after that is treated as a new request. Before retrying a submission that is more than a day old, look it up with `GET /v1/partner/consultations/?external_reference=` to check whether it was created. ## Example ```bash theme={null} KEY="order-8812-submit" curl -sS -i -X POST https://api.hi-doctor.ai/v1/partner/consultations/ \ -H "Authorization: Bearer $HD_PARTNER_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $KEY" \ --data @consultation.json ``` Running the same command again returns the same `201` body with `Idempotent-Replayed: true`. ## Frequently asked questions ### Which Partner API endpoints need an Idempotency-Key? Only POST /v1/partner/consultations/, where it is required. Without it the request fails with 400 idempotency\_key\_required. ### How long is an idempotency key remembered? 24 hours. A retry after that is treated as a new request, so look the consultation up by external\_reference first. ### What happens if I reuse a key with a different body? The request fails with 422 idempotency\_key\_reuse and nothing runs. Use a new key for a new request. ### Are failed requests stored under the key? No. Only successful submissions are stored, so after a 4xx error you can fix the request and send it again with the same key or a new one. ### Does a trailing slash change the idempotency check? Yes. The path is compared exactly as sent, so retry with the same URL as the first attempt. ### Does rotating my API key reset idempotency keys? No. Keys are scoped to your partner, the mode and the operation, not to the API key. ## Next steps > [card] [Submit a consultation](https://docs.hi-doctor.ai/partners/submit-a-consultation.md) > > The full submission contract. > [card] [Errors](https://docs.hi-doctor.ai/partners/errors.md) > > Every error code and how to recover. Commercial questions: read the [partnership FAQ](https://docs.hi-doctor.ai/partnerships/faq.md) or write to [hello@hi-doctor.ai](mailto:hello@hi-doctor.ai). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.