Partner API quickstart: your first test consultation

This quickstart creates your first Partner API consultation in test mode, in seven steps from a key check to a signed webhook. Test consultations are synthetic and never reach a doctor, so you can repeat the walkthrough as often as you like. You need a test key that starts with hdp_test_ and cURL, Node.js 18 or Python 3. Last reviewed: 2026-11-04 Every request on this page is listed in the generated Partner API reference. For the concepts behind the steps, read How the Partner API works.

Before you start

A test API key that starts with hdp_test_, with the scopes consultations:read, consultations:write, prescriptions:read and webhooks:manage. The first two cover steps 1 to 6; registering a webhook endpoint with the API in step 7 needs all four. Add patients:read if you also want to read the patients you create. See Authentication for every scope. Listing products and fetching a questionnaire need no scope. Your Hi Doctor contact issues the first key; after that you manage keys in the Business portal.
curl, Node.js 18 or later, or Python 3 with requests.

Set the key once in your shell:

export HD_PARTNER_API_KEY="hdp_test_..."
export HD_BASE_URL="https://api.hi-doctor.ai"

1. Check the key

GET /v1/partner/ping/ confirms the key is accepted and tells you its mode.

curl -sS "${HD_BASE_URL:-https://api.hi-doctor.ai}/v1/partner/ping/" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY"

const base = process.env.HD_BASE_URL ?? "https://api.hi-doctor.ai";
const response = await fetch(`${base}/v1/partner/ping/`, {
  headers: { Authorization: `Bearer ${process.env.HD_PARTNER_API_KEY}` },
});
console.log(response.status, await response.json());

import os
import requests

base = os.environ.get("HD_BASE_URL", "https://api.hi-doctor.ai")
response = requests.get(
    f"{base}/v1/partner/ping/",
    headers={"Authorization": f"Bearer {os.environ['HD_PARTNER_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

The response names your partner and the key’s mode:

{
  "ok": true,
  "partner": "your-partner-slug",
  "mode": "test",
  "key_id": "k1a2b3c4d5e6"
}

2. List your products for a country

GET /v1/partner/products/?country=NL returns the products in your agreement that are open in that country. Each product names its questionnaire and the current schema_version and schema_hash. Plans and dosages can only be chosen from this list.

curl -sS "${HD_BASE_URL:-https://api.hi-doctor.ai}/v1/partner/products/?country=NL" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY"

const base = process.env.HD_BASE_URL ?? "https://api.hi-doctor.ai";
const response = await fetch(`${base}/v1/partner/products/?country=NL`, {
  headers: { Authorization: `Bearer ${process.env.HD_PARTNER_API_KEY}` },
});
const { results } = await response.json();
for (const product of results) {
  console.log(product.product_id, product.questionnaire_slug, product.schema_version);
}

import os
import requests

base = os.environ.get("HD_BASE_URL", "https://api.hi-doctor.ai")
response = requests.get(
    f"{base}/v1/partner/products/",
    params={"country": "NL"},
    headers={"Authorization": f"Bearer {os.environ['HD_PARTNER_API_KEY']}"},
    timeout=30,
)
for product in response.json()["results"]:
    print(product["product_id"], product["questionnaire_slug"], product["schema_version"])

Each result has product_id, name, category, questionnaire_slug, schema_version, schema_hash, country, plans (plan_key, supply_days), dosages (dosage, label) and price (amount_cents, currency, as agreed in your partner agreement).

3. Fetch the questionnaire schema

GET /v1/partner/questionnaires/{slug}/ returns the schema the doctor’s review is based on. Set QUESTIONNAIRE_SLUG to the questionnaire_slug of the product you chose in step 2. Render every applicable step to the patient and collect the answers in the entries-v1 format. Questionnaires and schema documents every step kind.

curl -sS "${HD_BASE_URL:-https://api.hi-doctor.ai}/v1/partner/questionnaires/$QUESTIONNAIRE_SLUG/" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY"

const base = process.env.HD_BASE_URL ?? "https://api.hi-doctor.ai";
const slug = process.env.QUESTIONNAIRE_SLUG;
const response = await fetch(`${base}/v1/partner/questionnaires/${slug}/`, {
  headers: { Authorization: `Bearer ${process.env.HD_PARTNER_API_KEY}` },
});
const questionnaire = await response.json();
console.log(questionnaire.schema_version, questionnaire.schema_hash, questionnaire.answer_format);

import os
import requests

base = os.environ.get("HD_BASE_URL", "https://api.hi-doctor.ai")
slug = os.environ["QUESTIONNAIRE_SLUG"]
response = requests.get(
    f"{base}/v1/partner/questionnaires/{slug}/",
    headers={"Authorization": f"Bearer {os.environ['HD_PARTNER_API_KEY']}"},
    timeout=30,
)
questionnaire = response.json()
print(questionnaire["schema_version"], questionnaire["schema_hash"], questionnaire["answer_format"])

4. Upload a photo

Upload each photo the schema asks for with POST /v1/partner/files/ as multipart/form-data. JPEG, PNG and PDF are accepted, detected from the file’s bytes. Keep the returned upload_id. See Photos and files.

curl -sS -X POST "${HD_BASE_URL:-https://api.hi-doctor.ai}/v1/partner/files/" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY" \
  -F "purpose=photo" \
  -F "file=@body-photo.jpg"

import { readFile } from "node:fs/promises";

const base = process.env.HD_BASE_URL ?? "https://api.hi-doctor.ai";
const form = new FormData();
form.append("purpose", "photo");
form.append("file", new Blob([await readFile("body-photo.jpg")]), "body-photo.jpg");
const response = await fetch(`${base}/v1/partner/files/`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.HD_PARTNER_API_KEY}` },
  body: form,
});
const upload = await response.json();
console.log(response.status, upload.upload_id, upload.expires_at);

import os
import requests

base = os.environ.get("HD_BASE_URL", "https://api.hi-doctor.ai")
with open("body-photo.jpg", "rb") as photo:
    response = requests.post(
        f"{base}/v1/partner/files/",
        headers={"Authorization": f"Bearer {os.environ['HD_PARTNER_API_KEY']}"},
        data={"purpose": "photo"},
        files={"file": photo},
        timeout=60,
    )
upload = response.json()
print(response.status_code, upload["upload_id"], upload["expires_at"])

5. Submit the consultation

Put the request body in consultation.json. The question keys below are illustrative; use the keys from the schema you fetched. locale is one of the questionnaire locales served (en, es or zh; anything else falls back to English). Send the schema_hash from the schema you fetched; the hash of any served locale is accepted. An upload answer is the scalar "value": "<upload_id>".

{
  "product_id": "<product_id from step 2>",
  "country": "NL",
  "plan_key": "<plan_key from step 2>",
  "dosage": "<dosage from step 2>",
  "locale": "en",
  "schema_version": "<schema_version from step 3>",
  "schema_hash": "<schema_hash from step 3>",
  "external_reference": "ORDER-8812",
  "patient": {
    "external_patient_id": "u_123",
    "email": "patient@example.com",
    "first_name": "Sam",
    "last_name": "Example",
    "date_of_birth": "1988-04-02",
    "sex": "female",
    "consent": {
      "terms_accepted": true,
      "privacy_accepted": true,
      "clinical_data_processing_accepted": true,
      "accepted_at": "2026-11-03T10:14:00Z",
      "notice_version": "<current patient notice version>"
    }
  },
  "answers": [
    { "question_key": "height_weight", "values": { "height": 172, "weight": 96 } },
    { "question_key": "body_photo", "value": "<upload_id from step 4>" }
  ]
}

Send it with an Idempotency-Key that you create once for this consultation and store before the first attempt. If the request times out, rerun the same sample: it reads the stored key back, so the retry carries the same key and body and you get the original response instead of a second consultation. Delete idempotency-key.txt only when you submit a different consultation. See Partner API idempotency.

# Create the key once and keep it; a retry reuses the stored value.
[ -s idempotency-key.txt ] || uuidgen > idempotency-key.txt
curl -sS -X POST "${HD_BASE_URL:-https://api.hi-doctor.ai}/v1/partner/consultations/" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(tr -d '[:space:]' < idempotency-key.txt)" \
  --data @consultation.json

import { readFile, writeFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import { randomUUID } from "node:crypto";

const base = process.env.HD_BASE_URL ?? "https://api.hi-doctor.ai";
const body = await readFile("consultation.json", "utf8");
// Create the key once and keep it; a retry reuses the stored value.
const keyFile = "idempotency-key.txt";
if (!existsSync(keyFile)) await writeFile(keyFile, randomUUID());
const idempotencyKey = (await readFile(keyFile, "utf8")).trim();
const response = await fetch(`${base}/v1/partner/consultations/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HD_PARTNER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body,
});
const consultation = await response.json();
console.log(response.status, consultation.id, consultation.status, consultation.version);

import json
import os
import uuid
import requests

base = os.environ.get("HD_BASE_URL", "https://api.hi-doctor.ai")
with open("consultation.json") as handle:
    body = json.load(handle)
# Create the key once and keep it; a retry reuses the stored value.
key_file = "idempotency-key.txt"
if not os.path.exists(key_file):
    with open(key_file, "w") as handle:
        handle.write(str(uuid.uuid4()))
with open(key_file) as handle:
    idempotency_key = handle.read().strip()
response = requests.post(
    f"{base}/v1/partner/consultations/",
    headers={
        "Authorization": f"Bearer {os.environ['HD_PARTNER_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json=body,
    timeout=60,
)
consultation = response.json()
print(response.status_code, consultation["id"], consultation["status"], consultation["version"])

A 201 response returns the consultation resource with status: "submitted" and version: 1.

6. Move the test consultation and read it

In test mode nothing happens until you advance the consultation. Set CONSULTATION_ID to the id from the step 5 response, move the consultation to in_review, then read it back:

curl -sS -X POST "${HD_BASE_URL:-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": "in_review"}'

curl -sS "${HD_BASE_URL:-https://api.hi-doctor.ai}/v1/partner/consultations/$CONSULTATION_ID/" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY"

const base = process.env.HD_BASE_URL ?? "https://api.hi-doctor.ai";
const id = process.env.CONSULTATION_ID;
const headers = {
  Authorization: `Bearer ${process.env.HD_PARTNER_API_KEY}`,
  "Content-Type": "application/json",
};
await fetch(`${base}/v1/partner/test/consultations/${id}/advance/`, {
  method: "POST",
  headers,
  body: JSON.stringify({ to: "in_review" }),
});
const response = await fetch(`${base}/v1/partner/consultations/${id}/`, { headers });
const consultation = await response.json();
console.log(consultation.status, consultation.version);

import os
import requests

base = os.environ.get("HD_BASE_URL", "https://api.hi-doctor.ai")
consultation_id = os.environ["CONSULTATION_ID"]
headers = {"Authorization": f"Bearer {os.environ['HD_PARTNER_API_KEY']}"}
requests.post(
    f"{base}/v1/partner/test/consultations/{consultation_id}/advance/",
    headers=headers,
    json={"to": "in_review"},
    timeout=30,
)
consultation = requests.get(
    f"{base}/v1/partner/consultations/{consultation_id}/", headers=headers, timeout=30
).json()
print(consultation["status"], consultation["version"])

Polling works for a first test. In production, use webhooks and treat polling as a fallback.

7. Receive the webhook

Register an HTTPS endpoint for test mode in the Business portal or with POST /v1/partner/webhook-endpoints/ (scopes webhooks:manage, consultations:read and prescriptions:read). The response returns the signing secret once, as whsec_ followed by base64: store it straight away.

curl -sS -X POST "${HD_BASE_URL:-https://api.hi-doctor.ai}/v1/partner/webhook-endpoints/" \
  -H "Authorization: Bearer $HD_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url": "https://partner.example.com/hooks/hi-doctor", "events": ["*"], "description": "Quickstart"}'

Then advance the test consultation again, for example to approved. Each change produces one signed event whose data is the full consultation snapshot. Deliveries follow the Standard Webhooks specification: verify the webhook-id, webhook-timestamp and webhook-signature headers with the code in Webhooks, or any Standard Webhooks library, before trusting the body.

Frequently asked questions

Do test consultations reach a doctor?

No. Test consultations are synthetic, never reach a doctor, create no medical record and are never billed.

Why does my test consultation stay submitted?

Nothing moves on its own in test mode. Advance the consultation with the test advance endpoint to reach each status.

Which scopes does the quickstart key need?

consultations:read and consultations:write cover steps 1 to 6. Registering a webhook endpoint in step 7 also needs prescriptions:read and webhooks:manage.

Where do I get the questionnaire slug?

From the product list in step 2. Each product names its questionnaire_slug together with the current schema_version and schema_hash.

What happens if I retry the submission after a timeout?

Send the same Idempotency-Key and the same body. You get the original response instead of a second consultation.

Which locale should I send?

One of the questionnaire locales served, en, es or zh. Any other value falls back to English. Send the schema_hash from the schema you fetched; the hash of any served locale is accepted.

Do Partner API paths end with a slash?

The samples use the paths exactly as the Partner API reference lists them, with a trailing slash. Keep the same form on a retry, because an idempotent retry must use the same path as the first attempt.

Next steps

Questionnaires and schema

Render every step kind correctly.

Webhooks

Signatures, retries and the ordering rule.

Go-live checklist

What must be in place before live mode.

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

Start

Build

Operate

Partner API reference

Partner API quickstart: your first test consultation

Before you start

1. Check the key

2. List your products for a country

3. Fetch the questionnaire schema

4. Upload a photo

5. Submit the consultation

6. Move the test consultation and read it

7. Receive the webhook

Frequently asked questions

Do test consultations reach a doctor?

Why does my test consultation stay submitted?

Which scopes does the quickstart key need?

Where do I get the questionnaire slug?

What happens if I retry the submission after a timeout?

Which locale should I send?

Do Partner API paths end with a slash?

Next steps

Questionnaires and schema

Webhooks

Go-live checklist

​Before you start

​1. Check the key

​2. List your products for a country

​3. Fetch the questionnaire schema

​4. Upload a photo

​5. Submit the consultation

​6. Move the test consultation and read it

​7. Receive the webhook

​Frequently asked questions

​Do test consultations reach a doctor?

​Why does my test consultation stay submitted?

​Which scopes does the quickstart key need?

​Where do I get the questionnaire slug?

​What happens if I retry the submission after a timeout?

​Which locale should I send?

​Do Partner API paths end with a slash?

​Next steps

Questionnaires and schema

Webhooks

Go-live checklist

Before you start

1. Check the key

2. List your products for a country

3. Fetch the questionnaire schema

4. Upload a photo

5. Submit the consultation

6. Move the test consultation and read it

7. Receive the webhook

Frequently asked questions

Do test consultations reach a doctor?

Why does my test consultation stay submitted?

Which scopes does the quickstart key need?

Where do I get the questionnaire slug?

What happens if I retry the submission after a timeout?

Which locale should I send?

Do Partner API paths end with a slash?

Next steps