Partner API test mode: synthetic consultations

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

{
  "to": "info_requested",
  "reason_code": "photo_quality",
  "question_keys": ["body_photo"]
}

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 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 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?

Submit a test consultation. It is submitted, version 1.
Advance to in_review. You receive consultation.in_review.
Advance to info_requested with reason_code and question_keys. You receive consultation.info_requested.
Answer the request through the API, or advance to in_review. The consultation returns to in_review.
Advance to approved, then to prescription_issued. You receive consultation.approved and prescription.issued.
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 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

Quickstart

Run a first test consultation end to end.

Information requests

Read and answer a doctor’s request.

Commercial questions: read the partnership FAQ or write to hello@hi-doctor.ai.

Start

Build

Operate

Partner API reference

Partner API test mode: synthetic consultations

What is Partner API test mode?

Why does a test consultation not move on its own?

Advance a test consultation

In which order is the advance body checked?

How do I cover every branch in a test run?

How do I move from test to live?

Frequently asked questions

Do test consultations reach a doctor?

Are test webhooks signed like live webhooks?

How do I test an information request?

How do I get a test prescription?

Can a live key use the advance endpoint?

Does finishing test mode enable live mode?

Next steps

Quickstart

Information requests

​What is Partner API test mode?

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

​Advance a test consultation

​In which order is the advance body checked?

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

​How do I move from test to live?

​Frequently asked questions

​Do test consultations reach a doctor?

​Are test webhooks signed like live webhooks?

​How do I test an information request?

​How do I get a test prescription?

​Can a live key use the advance endpoint?

​Does finishing test mode enable live mode?

​Next steps

Quickstart

Information requests

What is Partner API test mode?

Why does a test consultation not move on its own?

Advance a test consultation

In which order is the advance body checked?

How do I cover every branch in a test run?

How do I move from test to live?

Frequently asked questions

Do test consultations reach a doctor?

Are test webhooks signed like live webhooks?

How do I test an information request?

How do I get a test prescription?

Can a live key use the advance endpoint?

Does finishing test mode enable live mode?

Next steps