Integrate the Partner API with an AI coding agent

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

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

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.

​

Where can the agent read the docs?

• /llms.txt: an index of the docs written for agents.
• /skill.md: reviewed rules an agent can load; installing it grants no permissions.
• /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

​

Next steps