> ## 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.

# Integrate the Partner API with an AI coding agent

> A copy-paste prompt and rules for building a Hi Doctor Partner API integration with an AI coding agent such as Claude Code, Cursor or ChatGPT.

To build a Hi Doctor Partner API integration with an AI coding agent such as Claude Code, Cursor or ChatGPT, paste the prompt below into the agent and point it at the Partner API reference. The prompt covers test keys, products, the questionnaire schema, one-call submission with an Idempotency-Key, uploads, signed webhooks, information requests and the go-live checklist. Review every change the agent makes before it touches live keys.

Last reviewed: 2026-11-05

Access to the Partner API is granted per partner agreement. Request access: [hello@hi-doctor.ai](mailto:hello@hi-doctor.ai)

> [!WARNING]
>
> The agent writes code; it never decides anything medical. Every consultation is
> reviewed in full by an EU-licensed doctor, who decides on medical grounds only.
> Keep API keys and webhook secrets out of the prompt and out of the agent's
> context: give the agent environment variable names, not values.

## What prompt should I give the coding agent?

Copy this prompt into your coding agent, then add your stack, framework and where your order data lives. Keep every rule.

Partner API integration prompt
Copy prompt to clipboard

<pre>
  \`Goal: add a Hi Doctor Partner API integration to this application. Hi Doctor is an online medical service: the partner platform sends a complete consultation, an EU-licensed doctor reviews it and decides on medical grounds only, and the platform tracks the result.

  Access: Access to the Partner API is granted per partner agreement. Request access: [hello@hi-doctor.ai](mailto:hello@hi-doctor.ai)

  Read first:

  * [https://docs.hi-doctor.ai/llms.txt](https://docs.hi-doctor.ai/llms.txt) (index of the docs)
  * [https://docs.hi-doctor.ai/skill.md](https://docs.hi-doctor.ai/skill.md) (reviewed rules)
  * [https://docs.hi-doctor.ai/api-reference/partner/openapi.json](https://docs.hi-doctor.ai/api-reference/partner/openapi.json) (Partner API schema; generate types from it)
  * [https://docs.hi-doctor.ai/partners/quickstart.md](https://docs.hi-doctor.ai/partners/quickstart.md)

  KEYS AND TEST MODE

  * Base URL [https://api.hi-doctor.ai](https://api.hi-doctor.ai). Send the header "Authorization: Bearer" followed by the key on every call, from the server only. Never ship a key to a browser or mobile app.
  * Read the key from an environment variable (HD\_PARTNER\_API\_KEY). Never print, log or commit it.
  * Build and test everything with a test key (hdp\_test\_...). Test consultations never reach a doctor. Call GET /v1/partner/ping/ to check the key and its mode.
  * Ask for the smallest scopes: consultations:read, consultations:write, prescriptions:read, and webhooks:manage only for the code that registers endpoints.

  PRODUCTS

  * GET /v1/partner/products/?country=XX lists the products in the agreement for one country. Plans and dosages can only be chosen from this list. Never hard-code prices or product ids.

  QUESTIONNAIRE SCHEMA

  * GET /v1/partner/questionnaires/{slug}/ returns the schema for the product. Render every applicable step to the patient, including conditional steps, exclusions and validation. Collect answers in the entries-v1 format.
  * Cache the schema by schema\_version and keep the schema\_hash you received. Send both with the submission.
  * On 409 schema\_outdated, fetch the schema again and ask the patient the new questions. Never fill in answers for the patient.

  SUBMIT (ONE CALL)

  * POST /v1/partner/consultations/ with product\_id, country, plan\_key, dosage when listed, schema\_version, schema\_hash, patient (identity and consent) and answers. There is no draft.
  * The Idempotency-Key header is required. Generate it once per order, store it with the order BEFORE sending, and reuse the same key, the exact URL /v1/partner/consultations/ (with the trailing slash) and the same body on every retry after a timeout or 5xx.
  * If any part of the body must change (new answers after 409 schema\_outdated, new consent after 422 consent\_notice\_outdated), generate and store a new Idempotency-Key. Reusing a key with a different body returns 422 idempotency\_key\_reuse.
  * Consent: the patient must actively accept; send the three consent flags as true, accepted\_at and the current notice\_version. On 422 consent\_notice\_outdated, show the current notice and ask again.
  * Map 422 errors back to the right question with errors\[].question\_key when present.
  * Read the result with GET /v1/partner/consultations/{consultation_id}/ (status, decision, open\_info\_request, prescriptions, cancellable) and one prescription with GET /v1/partner/prescriptions/{prescription_id}/ (prescriptions:read). List prescriptions with GET /v1/partner/prescriptions/.

  UPLOADS

  * Upload photos and documents with POST /v1/partner/files/ (multipart/form-data, purpose photo or document, sha256 recommended) close to submission, then put the returned upload\_id in the answer. Handle 422 upload\_unusable, 422 unsupported\_media and 422 file\_too\_large.

  WEBHOOKS

  * Register an HTTPS endpoint (Business portal or POST /v1/partner/webhook-endpoints/). Store the whsec\_ secret in a secret manager.
  * Verify every delivery with Standard Webhooks on the RAW body before parsing JSON. Read the three headers webhook-id, webhook-timestamp and webhook-signature. Strip the whsec\_ prefix from the secret, base64-decode the remainder and use those bytes as the HMAC key. Compute the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, allow a 300-second timestamp tolerance, accept any matching entry in webhook-signature (space-separated entries, each v1 followed by a comma and the base64 signature) and compare in constant time. A Standard Webhooks library is fine.
  * Answer 2xx quickly and process afterwards. Deduplicate on webhook-id. Keep only the highest version snapshot per consultation. Ignore unknown event types and fields.
  * Events: consultation.submitted, consultation.in\_review, consultation.info\_requested, consultation.approved, consultation.rejected, consultation.cancelled, consultation.updated, prescription.issued, prescription.cancelled, prescription.replaced.

  INFORMATION REQUESTS

  * On consultation.info\_requested, read GET /v1/partner/consultations/{consultation_id}/info-requests/, ask the patient the listed questions again, upload new files if needed, then POST /v1/partner/consultations/{consultation_id}/info-requests/{request_id}/answer/.

  STATUS: WEBHOOKS FIRST, POLLING AS BACKUP

  * Webhooks drive state. Add a reconciliation job that pages through GET /v1/partner/consultations/ in case your endpoint was down. Do not poll in a tight loop.
  * Statuses (the complete list): submitted, in\_review, info\_requested, approved, rejected, cancelled. An issued prescription is not a status: the consultation stays approved and you receive the prescription.issued event.
  * Cancel with POST /v1/partner/consultations/{consultation_id}/cancel/ only while cancellable is true.

  ERRORS

  * Branch on error.code and HTTP status, never on the message. Log request\_id. Retry unchanged only 409 idempotency\_in\_progress, 409 consultation\_busy, 429 and 5xx (with backoff).

  TESTS

  * Use POST /v1/partner/test/consultations/{consultation_id}/advance/ with "to" set to in\_review, info\_requested, approved, rejected or prescription\_issued to cover every branch, plus an information-request answer and a cancel. prescription\_issued is an advance target, not a status: it adds a synthetic prescription, leaves the status approved and sends the prescription.issued event.

  GO-LIVE CHECKLIST

  * Follow [https://docs.hi-doctor.ai/partners/go-live-checklist.md](https://docs.hi-doctor.ai/partners/go-live-checklist.md). Live mode is enabled by Hi Doctor per partner; a live key gets 403 partner\_not\_live until then.

  NEVER

  * Never promise a prescription or a review time in patient-facing copy. A doctor decides.
  * Never log API keys, webhook secrets, signatures or patient answers.
  * Never invent endpoints or fields. If something is not in the OpenAPI schema or the docs, stop and ask.\`
</pre>

Paste into

## How should the agent authenticate?

With one server-side API key per system, sent as `Authorization: Bearer <key>`. Start with a test key that begins with `hdp_test_`, give it the smallest scopes, and store it in a secret manager. Let the agent read an environment variable name; never paste the key itself into the chat. See [Authentication](https://docs.hi-doctor.ai/partners/authentication.md).

## How should it make submissions safe to retry?

Every `POST /v1/partner/consultations/` needs an `Idempotency-Key` header. Ask the agent to create the key once per order, store it before the request, and reuse the same key, URL and body after a timeout, so a retry returns the stored result instead of a second consultation. When the body has to change, for example new answers after `409 schema_outdated` or new consent after `422 consent_notice_outdated`, it needs a new key: an old key with a different body returns `422 idempotency_key_reuse`. See [Partner API idempotency](https://docs.hi-doctor.ai/partners/idempotency.md).

## How does test mode fit in?

Test keys create synthetic consultations that never reach a doctor and never move on their own. The agent should write tests that move each consultation through every status with `POST /v1/partner/test/consultations/{consultation_id}/advance/`, and check the matching webhook. The `prescription_issued` target is not a status: it adds a synthetic prescription, keeps the status `approved` and sends `prescription.issued`. See [Test mode](https://docs.hi-doctor.ai/partners/test-mode.md).

## What must the webhook handler do?

Verify the Standard Webhooks signature on the raw body, using the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers and the secret with its `whsec_` prefix stripped and the rest base64-decoded, answer `2xx` quickly, deduplicate on `webhook-id`, keep the highest `version` per consultation and ignore unknown event types. Review this handler line by line: it is the code an agent most often gets subtly wrong. See [Webhooks](https://docs.hi-doctor.ai/partners/webhooks.md#verify-the-signature).

## How should errors be handled?

Branch on `error.code` and the HTTP status, keep `request_id` in your logs, map `422` answer errors back to the question with `errors[].question_key`, and retry only the codes the guide marks as retryable. See [Partner API errors](https://docs.hi-doctor.ai/partners/errors.md).

## What has to be true before go-live?

Signed agreements, a correct patient experience, every branch proven in test mode, verified webhooks, safe keys and named contacts. Ask the agent to turn the checklist into tickets, then work through it with your Hi Doctor contact. See the [go-live checklist](https://docs.hi-doctor.ai/partners/go-live-checklist.md).

## Where can the agent read the docs?

* [/llms.txt](https://docs.hi-doctor.ai/llms.txt): an index of the docs written for agents.
* [/skill.md](https://docs.hi-doctor.ai/skill.md): reviewed rules an agent can load; installing it grants no permissions.
* [/api-reference/partner/openapi.json](https://docs.hi-doctor.ai/api-reference/partner/openapi.json): the Partner API schema, for generated types and clients.

## Frequently asked questions

### Which AI coding agents can I use?

Any agent that can read a prompt and edit your code, such as Claude Code, Cursor or ChatGPT. The prompt is plain text and names no tool-specific features.

### Should I give the agent my API key?

No. Give it the name of the environment variable that holds the key, and keep keys and webhook secrets in your secret manager. Never paste them into a chat.

### Can the agent create live consultations?

Build and test with a test key only. Live mode is enabled by Hi Doctor for each partner after the go-live checklist, and a live key gets 403 partner\_not\_live until then.

### Does the agent decide anything medical?

No. The agent writes integration code. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only.

### What should I review most carefully?

The webhook signature check, the idempotency key handling and the consent capture. These are the parts where a small mistake causes duplicate consultations, spoofed events or invalid consent.

### Where does the agent find the exact request and response fields?

In the Partner API OpenAPI schema at /api-reference/partner/openapi.json and in the partner guides. Tell the agent to stop and ask rather than invent a field.

### How do I get access to the Partner API?

Access to the Partner API is granted per partner agreement. Request access: [hello@hi-doctor.ai](mailto:hello@hi-doctor.ai)

## Next steps

> [card] [Partner API quickstart](https://docs.hi-doctor.ai/partners/quickstart.md)
>
> Your first test consultation in seven steps.

> [card] [Go-live checklist](https://docs.hi-doctor.ai/partners/go-live-checklist.md)
>
> What Hi Doctor checks before live mode.


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