> ## 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 test mode: synthetic consultations

> Build against the Hi Doctor Partner API with test keys: synthetic consultations that never reach a doctor, moved with an explicit advance endpoint.

Test mode lets you build and rehearse a whole Partner API integration with keys that start with `hdp_test_`. Test consultations are synthetic: they never reach a doctor, create no medical record and are never billed. Nothing moves on its own, so you advance each consultation yourself with the test advance endpoint and receive the same webhook events as in live mode.

Last reviewed: 2026-11-04

## What is Partner API test mode?

* You use a key that starts with `hdp_test_`. Every resource it creates is a test resource. Consultations, patients and webhook endpoints carry `"mode": "test"`; uploads, information requests, prescriptions and webhook deliveries have no `mode` field and belong to the key's mode.
* Test consultations are synthetic. **They never reach a doctor**, no medical record is created and nothing is billed.
* Test uploads are checked exactly like live uploads, but are never turned into patient documents.
* Test and live data never mix: a test key gets `404` for live resources and a live key gets `404` for test resources.
* Webhook endpoints are registered per mode. Test events go only to test endpoints, and are signed and sent with the same Standard Webhooks headers as live events, so the same verifier works in both modes.

## Why does a test consultation not move on its own?

A test consultation stays `submitted` until you move it. There is no automatic simulation, so your tests are deterministic.

### Advance a test consultation

`POST /v1/partner/test/consultations/{id}/advance/` moves a test consultation to the next status and emits the same webhook event a live consultation would. It requires `consultations:write` and answers `404` to a live key.

| Field | Type | Notes |
| - | - | - |
| `to` | string | Required. One of `in_review`, `info_requested`, `approved`, `rejected`, `prescription_issued`. `prescription_issued` is not a status: it adds a synthetic prescription and leaves the status `approved`. |
| `reason_code` | string | Optional, for `info_requested`. One of the [reason codes](https://docs.hi-doctor.ai/partners/information-requests.md#reason-codes), 1 to 32 characters. Defaults to `other_clarification`. |
| `question_keys` | array of strings | Optional, for `info_requested`. Question keys from the submitted schema that the synthetic request asks you to answer again, each a non-empty string of up to 128 characters. |

```json theme={null}
{
  "to": "info_requested",
  "reason_code": "photo_quality",
  "question_keys": ["body_photo"]
}
```

```bash theme={null}
curl -sS -X POST "https://api.hi-doctor.ai/v1/partner/test/consultations/$CONSULTATION_ID/advance/" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"to": "info_requested", "reason_code": "photo_quality", "question_keys": ["body_photo"]}'
```

The response is the updated consultation resource, the same body that [Consultation lifecycle](https://docs.hi-doctor.ai/partners/consultation-lifecycle.md) describes, and the matching webhook event, here `consultation.info_requested`, carries it as `data`.

### In which order is the advance body checked?

| Order | Check | Failure |
| - | - | - |
| 1 | Shape, on every request whatever the target: `to` is one of the statuses above, `reason_code` a non-empty string of at most 32 characters, `question_keys` a list of non-empty strings. `"reason_code": ""` fails even when `to` is `in_review`. | `422 invalid_request` |
| 2 | The transition: `to` must be allowed from the current status. | `422 illegal_transition` |
| 3 | Only on an allowed move to `info_requested`: `reason_code` is a documented reason code and every `question_keys` entry is a key of the submitted questionnaire. Other targets check only their shape. | `422 invalid_request` |

| From | Allowed `to` |
| - | - |
| `submitted` | `in_review` |
| `in_review` | `info_requested`, `approved`, `rejected` |
| `info_requested` | `in_review` (or answer the request through the API) |
| `approved` | `prescription_issued` (adds a synthetic prescription to `prescriptions[]`; the status stays `approved`, and each repeat adds another prescription) |

`info_requested` creates a synthetic [information request](https://docs.hi-doctor.ai/partners/information-requests.md) that you answer with the normal answer endpoint, so you can test that flow end to end.

## How do I cover every branch in a test run?

1. Submit a test consultation. It is `submitted`, version 1.
2. Advance to `in_review`. You receive `consultation.in_review`.
3. Advance to `info_requested` with `reason_code` and `question_keys`. You receive `consultation.info_requested`.
4. Answer the request through the API, or advance to `in_review`. The consultation returns to `in_review`.
5. Advance to `approved`, then to `prescription_issued`. You receive `consultation.approved` and `prescription.issued`.
6. Repeat with `rejected`, and cancel a fresh consultation straight after submission with `POST /v1/partner/consultations/{id}/cancel/` (not the advance endpoint), to cover every branch.

## How do I move from test to live?

Test mode proves your integration; it does not enable live mode. Live mode is enabled for each partner by Hi Doctor once the [Go-live checklist](https://docs.hi-doctor.ai/partners/go-live-checklist.md) is complete. Until then a live key gets `403 partner_not_live`.

## Frequently asked questions

### Do test consultations reach a doctor?

No. Test consultations are synthetic. They never reach a doctor, no medical record is created and nothing is billed.

### Are test webhooks signed like live webhooks?

Yes. Test events go only to test endpoints and are signed and sent with the same Standard Webhooks headers as live events, so the same verifier works in both modes.

### How do I test an information request?

Advance the consultation to info\_requested with a reason\_code and question\_keys. It creates a synthetic information request that you answer with the normal answer endpoint.

### How do I get a test prescription?

Advance the consultation to approved, then to prescription\_issued. Each repeat adds another synthetic prescription and the status stays approved.

### Can a live key use the advance endpoint?

No. The advance endpoint answers 404 to a live key and requires the consultations:write scope.

### Does finishing test mode enable live mode?

No. Hi Doctor enables live mode for each partner once the go-live checklist is complete. Until then a live key gets 403 partner\_not\_live.

## Next steps

> [card] [Quickstart](https://docs.hi-doctor.ai/partners/quickstart.md)
>
> Run a first test consultation end to end.

> [card] [Information requests](https://docs.hi-doctor.ai/partners/information-requests.md)
>
> Read and answer a doctor's request.

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.