Sign up a Hi Doctor patient over the REST API

Creating a Hi Doctor patient account over REST takes three calls: register with an email and password, verify the 6-digit code emailed to the patient, which also signs them in, and complete the profile before checkout. The patient must read the code from their own inbox, so this flow belongs in your application, never in a model prompt. Last reviewed: 2026-11-04

Building an AI assistant? The MCP connector can create an account too. Sign-in is delegated to hi-doctor.ai, where a patient can create an account with an emailed code, sign in with a password or with Google, and reset a password. The assistant never sees the password.

Hi Doctor is not an emergency service. If someone reports severe or sudden symptoms, direct them to their local emergency number instead of continuing a signup. See Safety.

How do you create and verify an account?

Send Content-Type: application/json and X-Brand-Slug: hi-doctor on every call. The patient types their password into your application’s form; it goes straight to the API and is never logged.

curl -X POST "https://api.hi-doctor.ai/v1/users/register/" \
  -H "Content-Type: application/json" \
  -H "X-Brand-Slug: hi-doctor" \
  -d '{
    "email": "patient@example.com",
    "password": "<a strong password>",
    "first_name": "Alex",
    "last_name": "Example",
    "locale": "en"
  }'

200

{ "message": "Please verify your email with OTP" }

Only email and password are required. The response is 200: the account is created when the code is verified.

Response	Meaning	What to do
`400`	Weak password, or the address belongs to an active account	Fix the input, or sign in instead
`406` `REGISTRATION_EMAIL_UNDELIVERABLE`	The address cannot receive mail	Ask for a different address; never retry
`429` `REGISTRATION_RATE_LIMITED`	A repeat within the 60-second cooldown	Wait `wait_seconds`, then try again

429

{
  "error": "Too many attempts. Please try again later.",
  "wait_seconds": 59,
  "retry_after_seconds": 59,
  "code": "registration_rate_limited",
  "error_name": "REGISTRATION_RATE_LIMITED"
}

The cooldown 429 also carries Retry-After: 59. Read either the header or wait_seconds; they hold the same number of seconds.

Verify the emailed code

A 6-digit code is emailed to the address. It is valid for 10 minutes. Ask the patient for it and pass it through.

curl -X POST "https://api.hi-doctor.ai/v1/users/verify-email/" \
  -H "Content-Type: application/json" \
  -H "X-Brand-Slug: hi-doctor" \
  -d '{ "email": "patient@example.com", "otp": "123456" }'

200

{ "refresh": "<refresh token>", "access": "<access token>" }

Success signs the patient in: store the tokens as described in Authentication. There is no separate sign-in call.

Response	Meaning
`400` `VERIFY_EMAIL_INVALID_REQUEST`	`email` or `otp` is missing
`400` with another `error_name`	The code is incorrect or expired, or the pending registration has expired
`429`	10 incorrect codes within an hour. Stop and wait

Until verification succeeds, POST /v1/users/token/ returns 401: verification_required while the code is still valid, invalid_credentials once it has expired (register again to get a new code).

Complete the profile

Checkout requires a complete profile. If anything is missing it refuses with PROFILE_INCOMPLETE and lists the gaps:

{ "error_name": "PROFILE_INCOMPLETE", "missing_fields": ["date_of_birth", "country_of_residence"] }

Fill exactly those fields, then retry checkout:

curl -X PATCH "https://api.hi-doctor.ai/v1/users/profile/me/" \
  -H "Authorization: Bearer $HD_ACCESS_TOKEN" \
  -H "X-Brand-Slug: hi-doctor" \
  -H "Content-Type: application/json" \
  -d '{ "date_of_birth": "1990-04-12", "country_of_residence": "DEU" }'

country_of_residence takes an ISO 3166-1 alpha-3 code from the table below.

How do you resend the verification code?

There is no resend endpoint. To send a new code, call POST /v1/users/register/ again with the same address after the 60-second cooldown. A repeat inside the cooldown returns 429 with wait_seconds; wait that long instead of looping. Tell the patient to check for the earlier email first.

Which country codes does the profile accept?

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. Send the patient’s country of residence as an ISO 3166-1 alpha-3 code:

Country	Code
Austria	`AUT`
Belgium	`BEL`
Bulgaria	`BGR`
Croatia	`HRV`
Cyprus	`CYP`
Czechia	`CZE`
Denmark	`DNK`
Estonia	`EST`
Finland	`FIN`
France	`FRA`
Germany	`DEU`
Greece	`GRC`
Hungary	`HUN`
Ireland	`IRL`
Italy	`ITA`
Latvia	`LVA`
Lithuania	`LTU`
Luxembourg	`LUX`
Malta	`MLT`
Netherlands	`NLD`
Poland	`POL`
Portugal	`PRT`
Romania	`ROU`
Slovakia	`SVK`
Slovenia	`SVN`
Spain	`ESP`
Sweden	`SWE`

Countries explains how the service works across these countries and in which languages.

What if the patient forgets their password?

POST /v1/users/forgot-password/ with email (and optionally locale) always returns the same generic 200 message, whether or not the account exists. A repeat within 60 seconds returns 429 with wait_seconds. An account created with Google returns 400 code: "google_account", since it has no password. POST /v1/users/reset-password/ with uid, token and new_password from the emailed link sets the new password. Existing refresh tokens are refused afterwards. Google sign-in over REST (POST /v1/users/google-login/) needs a Google ID token issued for Hi Doctor’s own Google OAuth client, so it serves Hi Doctor’s own apps. See Google sign-in. Patients who use Google can still connect an AI assistant through the MCP connector.

Frequently asked questions

How long is the verification code valid?

The 6-digit code expires after 10 minutes. After 10 incorrect codes within an hour, verification is blocked for a while; stop and wait instead of retrying.

Is the account created when the patient registers?

No. Registration only sends the code. The account is created, and the patient signed in, when the code is verified. While the emailed code is still valid, password sign-in returns 401 with the verification required code; after it expires, 401 with the invalid credentials code. Complete verification first.

What if the email address cannot receive mail?

Registration returns 406 with the undeliverable email error. Ask the patient for a different address; retrying the same one cannot succeed.

Which profile fields does checkout need?

Checkout lists any missing fields in its incomplete profile error. Fill exactly those fields with a profile update, then retry checkout. Hi Doctor serves residents of the 27 EU member states listed on this page. Send the patient’s actual country of residence; it is one of the profile fields checkout can ask for. No. An assistant should use the MCP connector, where the patient signs up and signs in on hi-doctor.ai and the assistant never sees the password.

Next steps

Authentication

Store and refresh tokens, and handle every sign-in failure.

Quickstart

Make the first authenticated read with the new account.

Errors and recovery

Cooldowns, throttles and error shapes in detail.

Account endpoints

Every account operation in one table.

Start

Conventions

Endpoints

Sign up a Hi Doctor patient over the REST API

How do you create and verify an account?

How do you resend the verification code?

Which country codes does the profile accept?

What if the patient forgets their password?

Frequently asked questions

How long is the verification code valid?

Is the account created when the patient registers?

What if the email address cannot receive mail?

Which profile fields does checkout need?

Next steps

Authentication

Quickstart

Errors and recovery

Account endpoints

​How do you create and verify an account?

​How do you resend the verification code?

​Which country codes does the profile accept?

​What if the patient forgets their password?

​Can a patient sign up with Google?

​Frequently asked questions

​How long is the verification code valid?

​Is the account created when the patient registers?

​Why does sign-in fail before verification?

​What if the email address cannot receive mail?

​Which profile fields does checkout need?

​Can someone outside the EU sign up?

​Can an AI assistant run this signup flow?

​Next steps

Authentication

Quickstart

Errors and recovery

Account endpoints

How do you create and verify an account?

How do you resend the verification code?

Which country codes does the profile accept?

What if the patient forgets their password?

Can a patient sign up with Google?

Frequently asked questions

How long is the verification code valid?

Is the account created when the patient registers?

Why does sign-in fail before verification?

What if the email address cannot receive mail?

Which profile fields does checkout need?

Can someone outside the EU sign up?

Can an AI assistant run this signup flow?

Next steps