The flow
1
Prepare the action
Call the tool with its normal arguments. Without
mode, a call prepares
the action; it does not change anything yet. The result has state: "awaiting_human", an operation_id (the same value is also returned as
confirmation_id), an approval_url, expires_at, a preview of the
exact targets and effects, and a next_action.2
Give the link to the person
Show the
approval_url to the person who owns the connection and ask them
to open it. The link is on mcp.hi-doctor.ai. Do not open it for them and
do not describe it as done.3
The person signs in and decides
The person signs in with their own Hi Doctor account on hi-doctor.ai. Hi
Doctor checks that it is the same account that prepared the action, then shows a summary written by Hi Doctor, not by the assistant.
The person selects Approve or Decline.
4
Poll the operation
Call
hidoctor_operation_get with the operation_id until the state is
no longer awaiting_human. It returns the state, expires_at and the
next_action. It never returns the preview or the business result.5
Commit with unchanged arguments
When the state is
approved, call the same tool again with exactly the
same business arguments, plus mode: "commit", the confirmation_id
and an idempotency_key. Hi Doctor checks the arguments against what was
approved, checks that the target has not changed, and runs the action
once.Commit call (arguments)
Approval links work only on connections made on or after 7 October 2026.
Older connections receive
reconnect_required: disconnect and connect again. See
What changes for existing connections.How long does an approval link last?
An approval link is valid for 15 minutes from preparation. Within that time the person can restart sign-in from the same link if it timed out. After the deadline, an operation that was not committed reportsexpired
and cannot run. Prepare the action again and send the new link.
A committed operation’s receipt stays readable for 30 days, as long as the
connection is still authorised.
Operation states
How do I retry safely?
Networks fail. The rules below make a retry safe instead of a duplicate.- Choose the key before the first commit. An
idempotency_keyis 8 to 128 letters, digits,_or-. Use one key per approved operation and keep it until the operation is finished. - Retry with the same key and arguments. After a timeout or a lost
response, call commit again with the same
confirmation_id, arguments and key. If the action already ran, you get the original result back. If it is still running or uncertain, you get its state and guidance, and nothing runs again. - Never re-prepare to escape a pending state. A new preparation is a new
operation. If the first one actually ran, the action would happen twice.
While an operation is
awaiting_human,executingoruncertain, keep following that operation. - Different key, same confirmation. Hi Doctor rejects it with
confirmation_consumed. - Same key, different operation. Hi Doctor rejects it with
idempotency_conflict.
Idempotency-Key,
so a repeated request is recognised end to end. The API side is described in
the idempotency guide.
A successful result proves that Hi Doctor recorded the action. For actions
that reach outside Hi Doctor, such as a message to the medical team or a plan change through Stripe, it
does not prove delivery or settlement. Read the resulting record before
telling the person that something arrived.
Errors
Every error also carries
retryable, state, next_action and a
correlation_id to quote when you contact Hi Doctor.
What can complete today
These tools run the whole flow, from preparation to a committed result:hidoctor_message_send, hidoctor_message_attachment_send,
hidoctor_questionnaire_submit, hidoctor_subscription_cancel,
hidoctor_subscription_reactivate, hidoctor_subscription_early_order,
hidoctor_renewal_confirm, hidoctor_documents_change and
hidoctor_consultation_images_change.
Actions that cannot complete yet
The other tools with approval links prepare their action and show it for approval, but the final commit is not available through the connector. Do these tasks on hi-doctor.ai instead, and tell the patient before they approve anything:hidoctor_profile_update, hidoctor_checkout_create,
hidoctor_prescription_request_reissue, hidoctor_progress_weight_delete,
hidoctor_progress_injection_delete, hidoctor_progress_note_delete,
hidoctor_referrals_activate, hidoctor_account_delete and
hidoctor_questionnaire_legacy_submit.
The patient reference marks these tools Available on
the website. The changelog records any change.
What is never automated
Frequently asked questions
How long is a Hi Doctor approval link valid?
15 minutes from preparation. After that the operation reports expired and must be prepared again.Can the assistant approve an action itself?
No. Only the account owner, signed in on Hi Doctor, can approve. An argument such as confirmed: true is rejected.What if the commit times out?
Repeat the same commit call with the same confirmation_id, arguments and idempotency_key. Hi Doctor checks what happened and never runs the action twice.Can I change the arguments after the person approved?
No. The commit must use exactly the approved arguments, otherwise Hi Doctor returns confirmation_arguments_changed. Prepare the action again instead.Why does a commit return backend_atomicity_required?
That action is approved through the connector but completed on hi-doctor.ai. Tell the patient before they approve, and send them to the website.Does succeeded mean a message was delivered?
It means Hi Doctor recorded the action. For actions that reach outside Hi Doctor, read the resulting record before telling the person something arrived.Next steps
Workflows
Approval links inside complete patient tasks.
Security
How the approval page authenticates the person.
Questionnaire guide
The guided questionnaire behind the questionnaire tools.
Agent quickstart
Build an agent that uses approval links end to end.