> ## 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. # List consultations > Your consultations in this key's mode, newest first, with cursor pagination. Requires the consultations:read scope. ### Access, effects and retries **Ownership:** The API key's own partner and mode (test or live). **Prerequisites:** A partner API key with the `consultations:read` scope. **Effects:** None. **Retries:** Safe to retry. ## OpenAPI ````yaml /api-reference/partner/openapi.json get /v1/partner/consultations/ openapi: 3.0.3 info: title: Hi Doctor Partner API version: '1.0' description: >- The Hi Doctor Partner API lets a partner submit online medical consultations for its patients, follow their clinical review, answer the doctor's information requests and read the resulting prescriptions. Partner requests use Authorization: Bearer with a partner API key; test keys and live keys are separate. See https://docs.hi-doctor.ai/partners/overview for the partner guides. contact: name: Hi Doctor email: hello@hi-doctor.ai url: https://docs.hi-doctor.ai servers: - url: https://api.hi-doctor.ai description: Production security: [] tags: - name: Connectivity description: Check that a key works. - name: Products description: What you can offer, where, and at what price. - name: Questionnaires description: The questions a patient answers for a product. - name: Files description: Photos and documents attached to answers. - name: Consultations description: Submit consultations and follow their review. - name: Patients description: The patients you submitted consultations for, and their consent. - name: Information requests description: Questions the doctor sends back during review. - name: Prescriptions description: Prescriptions issued after an approval. - name: Webhooks description: Receive events instead of polling. - name: Test mode description: Tools that only work with test keys. paths: /v1/partner/consultations/: get: tags: - Consultations summary: List consultations description: >- Your consultations in this key's mode, newest first, with cursor pagination. Requires the consultations:read scope. ### Access, effects and retries **Ownership:** The API key's own partner and mode (test or live). **Prerequisites:** A partner API key with the `consultations:read` scope. **Effects:** None. **Retries:** Safe to retry. operationId: list_consultations parameters: - in: query name: status schema: type: string enum: - approved - cancelled - in_review - info_requested - rejected - submitted description: Only consultations in this status. example: in_review - in: query name: external_patient_id schema: type: string description: >- Only consultations for the patient with this external_patient_id from your system. example: cust-8812 - in: query name: external_reference schema: type: string description: Only the consultation with this external_reference from your system. example: order-10045 - in: query name: created_after schema: type: string format: date-time description: Inclusive. example: '2026-11-01T00:00:00Z' - in: query name: created_before schema: type: string format: date-time description: Exclusive. example: '2026-11-04T00:00:00Z' - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 50 description: >- Page size, 1 to 100. Default 50. A value outside the range is refused with 400 invalid_request. example: 50 - in: query name: cursor schema: type: string description: The next_cursor of the previous page. example: >- MjAyNi0xMS0wM1QxMDoxNTowMCswMDowMHw3ZjhiMWMyZS00ZDVhLTRlNmYtOWEwYi0xYzJkM2U0ZjVhNmI= responses: '200': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: $ref: '#/components/schemas/ConsultationList' examples: example-1: value: object: list results: - id: 7f8b1c2e-4d5a-4e6f-9a0b-1c2d3e4f5a6b object: consultation mode: test status: approved version: 4 status_history: - status: submitted version: 1 at: '2026-11-03T10:15:00Z' - status: in_review version: 2 at: '2026-11-03T11:02:00Z' - status: approved version: 3 at: '2026-11-03T12:40:00Z' external_reference: order-10045 product: product_id: oral_finasteride name: Oral finasteride country: ES plan_key: one_off dosage: 1 mg patient: id: 0e1d2c3b-4a59-4687-8b9a-0b1c2d3e4f50 external_patient_id: cust-8812 submitted_at: '2026-11-03T10:15:00Z' updated_at: '2026-11-03T12:45:00Z' reviewer: description: Hi Doctor EU-licensed doctor licence_country: ES decision: outcome: approved reason_category: null decided_at: '2026-11-03T12:40:00Z' open_info_request: null prescriptions: - id: 5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d consultation_id: 7f8b1c2e-4d5a-4e6f-9a0b-1c2d3e4f5a6b status: issued active: true issued_at: '2026-11-03T12:45:00Z' cancelled_at: null expires_at: null dispensing_country: null medication: name: oral_finasteride prescribed_label: oral_finasteride dosage: 1 mg supply_days: null fulfilment: route: cross_border_pdf collected_at: null replaced_by: null billing: state: billable price: amount_cents: 2900 currency: EUR cancellable: false next_cursor: >- MjAyNi0xMS0wM1QxMDoxNTowMCswMDowMHw3ZjhiMWMyZS00ZDVhLTRlNmYtOWEwYi0xYzJkM2U0ZjVhNmI= summary: Illustrative response example description: Success. '400': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: invalid_request code: invalid_request message: limit must be between 1 and 100. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-2: value: error: type: invalid_request code: invalid_cursor message: The pagination cursor is not valid. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-3: value: error: type: invalid_request code: invalid_request message: created_after must be an ISO 8601 date-time. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-4: value: error: type: invalid_request code: brand_header_not_allowed message: >- Brand headers are not accepted on partner requests; the brand comes from the API key. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: >- The request is malformed. Partner routes also refuse the patient-app brand header with 400 brand_header_not_allowed, before authentication (no rate-limit headers). '401': headers: WWW-Authenticate: schema: type: string description: >- The authentication scheme to use: Bearer realm="hi-doctor-partner". content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: authentication_error code: not_authenticated message: Authentication credentials were not provided. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-2: value: error: type: authentication_error code: invalid_token message: The API key is not valid. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-3: value: error: type: authentication_error code: key_revoked message: The API key has been revoked. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-4: value: error: type: authentication_error code: key_expired message: The API key has expired. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-5: value: error: type: authentication_error code: partner_suspended message: The partner account is suspended. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: >- The API key is missing, malformed, unknown, revoked or expired, or the partner account is suspended. The response carries WWW-Authenticate: Bearer realm="hi-doctor-partner" and no rate-limit headers. '403': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: permission_error code: insufficient_scope message: This endpoint requires the consultations:read scope. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-2: value: error: type: permission_error code: partner_not_live message: Live mode is not enabled for this partner. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: >- The key lacks the consultations:read scope (insufficient_scope), or a live key was used while live mode is not enabled for the partner (partner_not_live). '404': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: anyOf: - $ref: '#/components/schemas/PartnerError' - $ref: '#/components/schemas/PartnerFlagOffError' examples: example-1: value: error: type: not_found summary: Illustrative response example description: >- While the Partner API is switched off for the environment, every route answers 404 with only {"error": {"type": "not_found"}}, before authentication. '429': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: rate_limited code: throttled message: Request was throttled. Expected available in 12 seconds. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: Too many requests; wait for the number of seconds in Retry-After. security: - PartnerApiKey: [] x-codeSamples: - lang: Shell label: curl source: > set -eu umask 077 # Path values must be URL-encoded; query string excludes the leading question mark. url="${HD_BASE_URL:?Set API origin}/v1/partner/consultations/${HD_QUERY_STRING:+?${HD_QUERY_STRING}}" printf 'Accept: application/json\n' > "${HD_REQUEST_HEADERS_FILE:?Private header file}" printf 'Authorization: Bearer %s\n' "${HD_PARTNER_API_KEY:?Set partner API key}" >> "$HD_REQUEST_HEADERS_FILE" curl --silent --show-error --max-time 30 --request GET \ --header "@$HD_REQUEST_HEADERS_FILE" \ --dump-header "${HD_HEADERS_FILE:?Private response header file}" \ --output "${HD_RESPONSE_FILE:?Private response file}" \ --write-out '%{http_code}\n%{content_type}\n' \ "$url" - lang: Python label: requests source: > import os, json from pathlib import Path from urllib.parse import quote import requests os.umask(0o077) url = os.environ["HD_BASE_URL"].rstrip("/") + '/v1/partner/consultations/' if os.environ.get("HD_QUERY_STRING"): url += "?" + os.environ["HD_QUERY_STRING"] headers = {"Accept": 'application/json'} headers["Authorization"] = "Bearer " + os.environ["HD_PARTNER_API_KEY"] kwargs = {} response = requests.request('GET', url, headers=headers, timeout=30, allow_redirects=False, **kwargs) Path(os.environ["HD_RESPONSE_FILE"]).write_bytes(response.content) Path(os.environ["HD_HEADERS_FILE"]).write_text(json.dumps(dict(response.headers))) print(response.status_code) print(response.headers.get("Content-Type", "")) - lang: JavaScript label: fetch source: > import { readFileSync, writeFileSync } from "node:fs"; const env = process.env; let url = env.HD_BASE_URL.replace(/\/$/, "") + "/v1/partner/consultations/"; if (env.HD_QUERY_STRING) url += "?" + env.HD_QUERY_STRING; const headers = { "Accept": "application/json" }; headers.Authorization = "Bearer " + env.HD_PARTNER_API_KEY; const options = { method: "GET", headers, redirect: "manual", signal: AbortSignal.timeout(30000) }; const response = await fetch(url, options); writeFileSync(env.HD_RESPONSE_FILE, Buffer.from(await response.arrayBuffer()), {mode: 0o600}); writeFileSync(env.HD_HEADERS_FILE, JSON.stringify(Object.fromEntries(response.headers)), {mode: 0o600}); console.log(response.status); console.log(response.headers.get("content-type") ?? ""); components: schemas: ConsultationList: type: object properties: object: allOf: - $ref: '#/components/schemas/ListObjectEnum' description: The object type. results: type: array items: $ref: '#/components/schemas/Consultation' description: The items on this page. next_cursor: type: string nullable: true description: Cursor for the next page; null on the last page. required: - next_cursor - object - results PartnerError: type: object properties: error: allOf: - $ref: '#/components/schemas/PartnerErrorDetail' description: The error. required: - error PartnerFlagOffError: type: object description: >- The reduced body every route answers while the Partner API is switched off for the environment: no code, message or request_id. properties: error: type: object properties: type: type: string enum: - not_found description: Always not_found. required: - type additionalProperties: false description: Only the error type; no code, message or request_id. required: - error additionalProperties: false ListObjectEnum: enum: - list type: string Consultation: type: object properties: id: type: string format: uuid description: The consultation id. object: allOf: - $ref: '#/components/schemas/ConsultationObjectEnum' description: Always consultation. mode: allOf: - $ref: '#/components/schemas/ModeEnum' description: test or live, from the API key. status: allOf: - $ref: '#/components/schemas/ConsultationStatusEnum' description: Current consultation status. version: type: integer description: >- Increases with every change to the consultation's public state, i.e. every field of this object except version, status_history, updated_at and product.name (catalogue copy: a product rename does not advance it). Events carry the same number. status_history: type: array items: $ref: '#/components/schemas/StatusHistoryEntry' description: Every status change, oldest first. external_reference: type: string nullable: true description: Your order or case reference; null when none was sent. product: allOf: - $ref: '#/components/schemas/ConsultationProduct' description: The product. country: type: string description: ISO 3166-1 alpha-2 country code. plan_key: type: string nullable: true description: The chosen plan. dosage: type: string nullable: true description: The chosen dosage; null when the product has none. patient: allOf: - $ref: '#/components/schemas/ConsultationPatientRef' description: The patient. submitted_at: type: string format: date-time description: When the consultation was submitted. updated_at: type: string format: date-time description: When it last changed. reviewer: description: Present once the reviewing doctor has opened the case. anyOf: - $ref: '#/components/schemas/Reviewer' - enum: - null type: string nullable: true decision: description: The clinical decision; null until one is recorded. anyOf: - $ref: '#/components/schemas/Decision' - enum: - null type: string nullable: true open_info_request: description: The open information request; null when there is none. anyOf: - $ref: '#/components/schemas/OpenInfoRequest' - enum: - null type: string nullable: true prescriptions: type: array items: $ref: '#/components/schemas/Prescription' description: Prescriptions issued for the consultation. billing: allOf: - $ref: '#/components/schemas/Billing' description: Billing state and price of the consultation. cancellable: type: boolean description: >- true exactly when POST /consultations/{consultation_id}/cancel would succeed now: the consultation is submitted, has no prescription, and (live) no doctor has opened it, no decision or electronic prescription signing has started, and no prescription issuance or replacement is in flight. required: - billing - cancellable - country - decision - dosage - external_reference - id - mode - object - open_info_request - patient - plan_key - prescriptions - product - reviewer - status - status_history - submitted_at - updated_at - version PartnerErrorDetail: type: object properties: type: allOf: - $ref: '#/components/schemas/PartnerErrorDetailTypeEnum' description: >- Error type, for example validation_error or rate_limited; see Errors in the partner guides. code: type: string description: A stable, machine-readable error code. message: type: string description: A human-readable explanation; do not parse it. errors: type: array items: $ref: '#/components/schemas/PartnerErrorItem' description: Field-level problems, when any. request_id: type: string description: Quote this identifier when you contact support. current: allOf: - $ref: '#/components/schemas/SchemaVersion' description: >- On 409 schema_outdated: the schema_version and schema_hash currently published. current_notice_version: type: string description: >- On 422 consent_notice_outdated: the patient notice version to show and record. required: - code - message - request_id - type ConsultationObjectEnum: enum: - consultation type: string ModeEnum: enum: - live - test type: string ConsultationStatusEnum: enum: - submitted - in_review - info_requested - approved - rejected - cancelled type: string StatusHistoryEntry: type: object properties: status: allOf: - $ref: '#/components/schemas/ConsultationStatusEnum' description: The status entered. version: type: integer description: Consultation version at this status. at: type: string format: date-time description: When the consultation entered this status. required: - at - status - version ConsultationProduct: type: object properties: product_id: type: string description: Product id from GET /v1/partner/products. name: type: string description: Product display name. required: - name - product_id ConsultationPatientRef: type: object properties: id: type: string format: uuid description: The patient id. external_patient_id: type: string description: Your stable identifier for the patient. required: - external_patient_id - id Reviewer: type: object properties: description: type: string description: Who reviewed the consultation. licence_country: type: string nullable: true description: >- ISO 3166-1 alpha-2 country of the reviewing doctor's licence; null when not recorded. required: - description - licence_country Decision: type: object properties: outcome: allOf: - $ref: '#/components/schemas/DecisionOutcomeEnum' description: approved or rejected. reason_category: oneOf: - $ref: '#/components/schemas/ReasonCategoryEnum' - $ref: '#/components/schemas/NullEnum' description: Category of a rejection; null otherwise. decided_at: type: string format: date-time nullable: true description: When the decision was recorded. required: - decided_at - outcome - reason_category OpenInfoRequest: type: object properties: id: type: string format: uuid description: The information request id. reason_code: allOf: - $ref: '#/components/schemas/ReasonCodeEnum' description: Why the doctor needs more information. requested_at: type: string format: date-time nullable: true description: When the doctor raised the request. required: - id - reason_code - requested_at Prescription: type: object properties: id: type: string format: uuid description: The prescription id. consultation_id: type: string format: uuid nullable: true description: The consultation this belongs to. status: allOf: - $ref: '#/components/schemas/PrescriptionStatusEnum' description: >- issued until the prescription is cancelled. It does not say whether the prescription can still be used: read active, and compare expires_at yourself. active: type: boolean description: >- false once the prescription is cancelled or no longer published to the patient, for example after a dispensing is recorded during a manual recovery. It does not check expiry: an expired prescription can stay active true, so compare expires_at yourself. issued_at: type: string format: date-time nullable: true description: When the prescription was issued. cancelled_at: type: string format: date-time nullable: true description: When the prescription was cancelled; null if it was not. expires_at: type: string format: date-time nullable: true description: >- When the prescription expires, or null when not recorded. Always null in test mode. dispensing_country: type: string nullable: true description: >- ISO 3166-1 alpha-2 country where the prescription is dispensed, or null when not recorded. Always null in test mode. medication: allOf: - $ref: '#/components/schemas/Medication' description: The prescribed medication. fulfilment: allOf: - $ref: '#/components/schemas/Fulfilment' description: How the patient obtains the medication. collected_at: type: string format: date-time nullable: true description: When the medication was collected, when known; otherwise null. replaced_by: type: string format: uuid nullable: true description: The prescription that replaced this one. required: - active - cancelled_at - collected_at - consultation_id - dispensing_country - expires_at - fulfilment - id - issued_at - medication - replaced_by - status Billing: type: object properties: state: oneOf: - $ref: '#/components/schemas/BillingStateEnum' - $ref: '#/components/schemas/NullEnum' description: pending, billable, void or reversed. price: allOf: - $ref: '#/components/schemas/Money' description: Price agreed for the consultation. required: - price - state PartnerErrorDetailTypeEnum: enum: - api_error - authentication_error - conflict - invalid_request - not_found - permission_error - rate_limited - validation_error type: string PartnerErrorItem: type: object properties: field: type: string nullable: true description: The request field the problem refers to, or null when none. question_key: type: string nullable: true description: >- The questionnaire question the problem refers to, or null when the entry named none. code: type: string description: Machine-readable error code for this item. message: type: string description: Human-readable message. It never repeats the submitted value. min: type: number format: double description: 'On out_of_range: the lowest allowed value, when the schema sets one.' max: type: number format: double description: >- On out_of_range: the highest allowed value, when the schema sets one. required: - code - message SchemaVersion: type: object properties: schema_version: type: string description: The published schema_version. schema_hash: type: string description: A hash accepted for the published version. required: - schema_hash - schema_version DecisionOutcomeEnum: enum: - approved - rejected type: string ReasonCategoryEnum: enum: - safety - not_eligible type: string NullEnum: enum: - null type: string nullable: true ReasonCodeEnum: enum: - answer_unclear - answer_inconsistent - photo_quality - photo_missing - measurement_check - medication_history - medical_history - identity_check - document_missing - identity_document_required - other_clarification type: string PrescriptionStatusEnum: enum: - issued - cancelled type: string Medication: type: object properties: name: type: string description: Medication name. prescribed_label: type: string description: The medication as prescribed. dosage: type: string nullable: true description: Prescribed dosage. supply_days: type: integer nullable: true description: Days of supply prescribed. required: - dosage - name - prescribed_label - supply_days Fulfilment: type: object properties: route: allOf: - $ref: '#/components/schemas/FulfilmentRouteEnum' description: How the patient obtains the medication; see the fulfilment guide. required: - route BillingStateEnum: enum: - pending - billable - void - reversed type: string Money: type: object properties: amount_cents: type: integer description: Amount in the currency's minor unit. currency: type: string description: ISO 4217 currency code. required: - amount_cents - currency FulfilmentRouteEnum: enum: - national_e_prescription - signed_pdf - pharmacy_delivery - cross_border_pdf type: string securitySchemes: PartnerApiKey: type: http scheme: bearer bearerFormat: API key description: >- Partner API key sent as Authorization: Bearer . Test keys and live keys are separate. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.