# VSee Clinic User API
Landing: https://developers.vsee.io/api/user-api  ·  Spec JSON: https://developers.vsee.io/specs/user_api_openapi.json
Base URL: https://api.vseepreview.com/api_v3

The VSee Clinic User API allows developers to manage users, authentication, and profiles
within the VSee Clinic platform.


### User Types
| Value | Meaning | Description |
|-------|---------|-------------|
| 100 | Admin | Admin user |
| 200 | Member | A registered patient |
| 300 | Company | Company user |
| 400 | Provider | Physician or CSR |
| 500 | Kiosk | Deprecated |
| 600 | Guest | Guest one-time user |
| 700 | Phone Bridge | User joined by dial-in |

### Provider Subtypes
| Value | Meaning |
|-------|---------|
| 460 | Medical Assistant |
| 470 | CSR (Customer Service Representative) |
| 480 | Paramedic / Remote Medic |
| 482 | Doctor / Licensed Service Provider |
| 484 | Nurse / Remote Medic |


## GET /users
URL: https://developers.vsee.io/api/user-api/get/users
operationId: getUsers
Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App).

List users

Retrieve a list of users with optional filtering and sorting.

**Tip:** Wherever there's a user `:id` field in API methods, it also accepts dash (`-`) as a mapping to the current user.

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code
- id (query, string, optional) — Filter by user ID(s). Accepts single ID, comma-separated string, or array. E.g: `123` or `"1234,1235"` or `[1234, 1235]`
- full_name (query, string, optional) — Full text search by name (minimum 3 characters)
- email (query, string, optional) — Like search by email (minimum 3 characters)
- q (query, string, optional) — Search keyword (minimum 3 chars). Searches `full_name` and `email`. Should be used in conjunction with `type`.
- type (query, string, optional) — User type. E.g: `400` or `"200,600"`. Types: 100=Admin, 200=Member, 400=Provider, 600=Guest
- status (query, string, optional) — User status. Accepts single value, comma-separated, or array. E.g: `20` or `"10,20"`
- role (query, string, optional) — Filter by role. E.g: `"clinic_admin"` or `"clinic_admin,scheduler"`
- ex_filter (query, string, optional) — Extended filter: `all` (filter by assigned rooms) or `my-patient` (filter by own visits) [enum: all, my-patient]
- is_hidden (query, boolean, optional) — Hide/Unhide patient from patient list (RPM feature)
- is_admin (query, boolean, optional) — Filter admin users
- room_code (query, string, optional) — Filter by room code
- account_code (query, string, optional)
- group (query, string, optional) — Filter by clinic group
- subtype (query, string, optional) — Provider sub type. Values: 480=Paramedic, 482=Doctor, 484=Nurse, 470=CSR, 460=Medical Assistant
- sort (query, string, optional) — Sort order. E.g: `"full_name.asc"` or `{full_name: "asc"}`
- start (query, integer, optional) — Offset for pagination [default: 0]
- limit (query, integer, optional) — Page size for pagination [default: 20]
- fields (query, string, optional) — Comma-separated fields to return. Available: `id`, `username`, `first_name`, `last_name`, `full_name`, `last_login`, `type`, `subtype`

Responses:
- 200 — Successful response
```json
{
  "data": [
    {
      "email": "anton+patient1@vseelab.com",
      "id": "20008869839",
      "full_name": "Anton Patient1"
    },
    {
      "email": "anton+patient2@vseelab.com",
      "id": "20008869840",
      "full_name": "Anton Patient2"
    }
  ],
  "total_count": 500
}
```
- 400 — Bad Request
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## GET /users/{id}
URL: https://developers.vsee.io/api/user-api/get/users/%7Bid%7D
operationId: getUserById
Auth: User Token — Requires a user access token from login or SSO.

Get user by ID

Get profile data of a particular user, including fields from the extended profile (if any).

**Tip:** The `:id` parameter also accepts dash (`-`) to refer to the current authenticated user.

Returns the full profile including extended profile fields, rooms, clinics, and account info.

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code
- id (path, string, required) — User ID, or `-` for the current user

Responses:
- 200 — Successful response
```json
{
  "data": {
    "id": "27769243",
    "code": "63f67706de344db98a6461d00adc646e",
    "first_name": "anton",
    "last_name": "test_2",
    "full_name": "anton test_2",
    "username": "anton+test2@vseelab.com",
    "vseeid": "cmo+user27769243",
    "dob": "1980-01-01",
    "email": "anton+test2@vseelab.com",
    "gender": 1,
    "active": true,
    "tos": true,
    "status": 20,
    "subtype": "",
    "timezone": "Europe/Berlin",
    "email_verified": true,
    "signup_step": 99,
    "extra": {
      "marital_status": "married",
      "gender_identity": "Choose Not To Disclose",
      "social_security_no": "",
      "veteran": "",
      "race": "",
      "ethnicity": "",
      "health_insurance": "",
      "insurance": "",
      "insurance_policy_number": "",
      "attachments": null,
      "emerg_contact_name": ""
    },
    "account_code": "vclinic",
    "clinics": [
      "vclinic"
    ],
    "rooms": [
      {
        "id": "865244556",
        "code": "vclinic_room_code",
        "slug": "uat",
        "name": "UAT",
        "account_code": "vclinic",
        "domain": "vclinic.vsee.me",
        "default": true,
        "added_time": 1677096710,
        "source": "signup"
      }
    ],
    "created": 1677096710,
    "type": 200
  }
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```
- 404 — Not Found
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## POST /users/sso
URL: https://developers.vsee.io/api/user-api/post/users/sso
operationId: ssoUser
Auth: API Key + Secret — Requires API Key and API Secret issued during onboarding.

Single Sign On (SSO)

Single Sign On for patient and provider. This is disabled by default — contact admin@vsee.com to request it.

SSO will create a user record on VSee side when you first call this API and will map to and return the existing user record for further requests.

Use `?fields=vsee` to include VSee ID and token in the response (for Browser Call SDK workflow).

**Important:** SSO is disabled by default. Contact admin@vsee.com to request activation.

SSO creates a user record on VSee side on first call and returns the existing user for subsequent requests using the same `code`.

**Tip:** Use `POST /users/sso?fields=vsee` to include the VSee ID and token in the response for Browser Call SDK workflow.

### E-Prescribe Requirements
To enable e-prescribing for a patient (type=200), the following additional fields are **required** in the SSO call:
- `gender` (string): `male` or `female`
- `street_addr` (string): Patient's street address
- `city` (string): Patient's city
- `state` (string): Two-letter state abbreviation
- `zip` (string): ZIP code
- `phone` (string): Phone number
- `dob` (string): Date of birth in YYYY-MM-DD format

### SSO Types
- **Guest SSO** (type=600): Creates a one-time guest user. No `code` required.
- **Patient SSO** (type=200): Creates/returns a registered patient. `code` is required (max 128 chars).
- **Provider SSO** (type=400): Creates/returns a provider. `code` is required (max 128 chars).

### Response Token
Use `data.token.token` to redirect user to VSee Clinic portal via the `/auth` endpoint.

Parameters:
- X-ApiKey (header, string, required) — API Key
- X-ApiSecret (header, string, required) — API Secret
- X-AccountCode (header, string, required) — Account code
- fields (query, string, optional) — Include additional fields in response. Use `vsee` to get VSee ID and token for Browser Call SDK. [enum: vsee]

Request body (multipart/form-data):
- first_name (string, required) — User's first name
- last_name (string, required) — User's last name
- type (integer, required) — User type: 200 (Member/Patient), 400 (Provider), 600 (Guest) [enum: 200, 400, 600]
- code (string, optional) — Required if type is 200 or 400. Max length 128 characters. A unique user identifier on your end. VSee stores this code and returns the same user on subsequent SSO calls.
- dob (string, optional) — Date of birth in YYYY-MM-DD format
- email (string, optional) — User email address
- username (string, optional) — Optional — system will generate one as fallback
- disable_emails (integer, optional) — Set to `1` to disable all email notifications [enum: 0, 1]
- gender (string, optional) — Required for e-prescribe. `male` or `female` [enum: male, female]
- street_addr (string, optional) — Required for e-prescribe
- city (string, optional) — Required for e-prescribe
- state (string, optional) — Required for e-prescribe. Two-letter state abbreviation
- zip (string, optional) — Required for e-prescribe
- phone (string, optional) — Required for e-prescribe

Example request:
```json
{
  "first_name": "John",
  "last_name": "Smith",
  "type": 600
}
```

Responses:
- 200 — Successful SSO response
```json
{
  "data": {
    "id": "10008",
    "code": "57d76ada0bb444f9b3057855ac1f0144",
    "first_name": "John",
    "last_name": "Smith",
    "username": "57d76ad979b843e6973e7855ac1f0144",
    "vseeid": "conciergedev+57d76ad979b843e6973e7855ac1f0144",
    "dob": "1990-01-01",
    "active": true,
    "tos": false,
    "subtype": "",
    "token": {
      "user_id": "10008",
      "token": "0437c1ce3b7079906e2ff247aad1adda",
      "expiry": 1473821786,
      "refresh_token": {
        "user_id": "10008",
        "token": "2693615fd2a46edf13334b3f35580e26",
        "expiry": 1476327386,
        "created": 1473735386
      }
    }
  }
}
```
- 400 — Bad Request
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## GET /auth
URL: https://developers.vsee.io/api/user-api/get/auth
operationId: authRedirect
Auth: No Auth — This endpoint requires no authentication headers.

SSO redirect login

Use this URL to redirect a user to VSee Clinic with automatic login.

Pattern: `https://{portal_url}/auth?sso_token={token}&next={next_url}`

This will log the user in and redirect them to the specified URL path.

Parameters:
- sso_token (query, string, required) — SSO token from the POST /users/sso response
- next (query, string, optional) — URL path to redirect the user to after login
- one_time_token (query, string, optional) — Set to `1` to invalidate the sso_token after login (additional security) [enum: 1]
- disable_navigation (query, string, optional) — Set to `1` to disable all email communication [enum: 1]

Responses:
- 302 — Redirects user to VSee Clinic portal

## GET /me
URL: https://developers.vsee.io/api/user-api/get/me
operationId: getMe
Auth: User Token — Requires a user access token from login or SSO.

Get current user profile

Retrieve the profile of the currently authenticated user.

Parameters:
- X-ApiToken (header, string, required) — API token
- user_photo_size (query, string, optional) — User photo dimensions in WxH format (e.g. `320x240`)

Responses:
- 200 — Successful response
```json
{
  "data": {
    "id": "201",
    "first_name": "An",
    "last_name": "Nguyen",
    "username": "member-201",
    "dob": "1960-01-01",
    "email": "an+user1@vsee.com",
    "gender": 2,
    "active": true,
    "nationality": "Vietnamese",
    "tos": false,
    "photo": "https://api.vseepreview.com/api_v3/files/57e8c9a2-5c30-4b2c-b9d0-11d6ac1f0144?size=320x240"
  }
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## POST /me
URL: https://developers.vsee.io/api/user-api/post/me
operationId: updateMe
Auth: User Token — Requires a user access token from login or SSO.

Update current user profile

Update the profile of the currently authenticated user.

Parameters:
- X-ApiToken (header, string, required) — API token

Request body (application/x-www-form-urlencoded):
- first_name (string, optional)
- last_name (string, optional)
- password (string, optional) — Send alone for first-time password set, or with old_password to change it
- old_password (string, optional) — Required when changing password
- dob (string, optional) — Date of birth (YYYY-MM-DD)
- gender (string, optional) [enum: male, female]
- nationality (string, optional)
- tos (integer, optional) — 0 - not accepted, 1 - accepted Terms of Service [enum: 0, 1]
- phone (string, optional)
- street_addr (string, optional)
- state (string, optional) — 2-letter state code
- zip (string, optional)
- city (string, optional)
- pcp_name (string, optional) — Primary Care Physician Name
- pcp_phone (string, optional) — Primary Care Physician Phone (10 digits)
- timezone (string, optional) — Timezone string (e.g. `America/New_York`, `Asia/Tokyo`)
- photo (string, optional) — File ID from POST /files API. Pass empty string to delete avatar.

Example request:
```json
{
  "password": "example_password",
  "dob": "1983-10-02",
  "nationality": "Vietnamese"
}
```

Responses:
- 200 — Successful update
```json
{
  "data": {
    "id": "201",
    "first_name": "An",
    "last_name": "Nguyen",
    "username": "member-201",
    "dob": "1983-10-02",
    "email": "an+user1@vsee.com",
    "gender": 2,
    "active": true,
    "nationality": "Vietnamese",
    "tos": true
  }
}
```
- 400 — Bad Request
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## POST /users/logout
URL: https://developers.vsee.io/api/user-api/post/users/logout
operationId: logoutUser
Auth: User Token — Requires a user access token from login or SSO.

Logout

Log the current user session out. The supplied tokens will be destroyed.

Parameters:
- X-ApiToken (header, string, required) — API token

Request body (application/x-www-form-urlencoded):
- tokens (string, optional) — Comma-separated tokens to destroy, e.g. `token1,token2`

Example request:
```json
{
  "tokens": "token1,token2"
}
```

Responses:
- 200 — Successful logout
```json
{
  "data": true
}
```

## POST /tokens/refresh
URL: https://developers.vsee.io/api/user-api/post/tokens/refresh
operationId: refreshToken
Auth: Account Code Only — Only requires the X-AccountCode header. No token needed.

Refresh access token

Use a refresh token to generate a new access token. A new refresh token is also returned for the next refresh.

Parameters:
- X-AccountCode (header, string, required) — Account code

Request body (application/x-www-form-urlencoded):
- refresh_token (string, required) — The refresh token from a previous login or refresh response

Example request:
```json
{
  "refresh_token": "6366a7018a39536a1ef4b63626f8e734"
}
```

Responses:
- 200 — New token pair
```json
{
  "data": {
    "user_id": "201",
    "user_type": "200",
    "token": "b21ab6cb871fa452a1193f0fbcf400d5",
    "expiry": 1426236055,
    "user": {
      "id": "201",
      "code": "55011c6c5b5c4aed99624956c0a801ee",
      "username": "member-201",
      "first_name": "Kristopher",
      "last_name": "Nieves (201)",
      "email": "an+user1@vsee.com",
      "dob": "1960-01-01",
      "gender": "Female"
    }
  }
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## POST /users/reset_password
URL: https://developers.vsee.io/api/user-api/post/users/reset_password
operationId: resetPassword
Auth: Account Code Only — Only requires the X-AccountCode header. No token needed.

Reset password

Send a reset password email to the supplied email address if valid.

Parameters:
- X-AccountCode (header, string, required) — Account code

Request body (application/x-www-form-urlencoded):
- email (string, required) — Valid email to send reset password email

Example request:
```json
{
  "email": "an+1@vsee.com"
}
```

Responses:
- 200 — Reset email sent
```json
{
  "data": true
}
```
- 400 — Bad Request
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## POST /users/alive
URL: https://developers.vsee.io/api/user-api/post/users/alive
operationId: keepAlive
Auth: User Token — Requires a user access token from login or SSO.

Keep alive

Send a heartbeat signal to indicate the user is online. Required when a user is in a critical workflow such as waiting for a provider to call.

Send at an interval less than 1/2 of the heartbeat value. Only "alive" patients show up on the provider dashboard.

Parameters:
- X-ApiToken (header, string, required) — API token

Request body (application/x-www-form-urlencoded):
- heartbeat (integer, optional) — Custom heartbeat value in seconds (default: 300s). For mobile, set to ~300s and update every ~250s.

Example request:
```json
{
  "heartbeat": 300
}
```

Responses:
- 200 — Heartbeat acknowledged
```json
{
  "data": {
    "last_connected": 1423023124,
    "heartbeat": 300
  }
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## POST /users/activate
URL: https://developers.vsee.io/api/user-api/post/users/activate
operationId: activateUser
Auth: Account Code Only — Only requires the X-AccountCode header. No token needed.

Activate user

Checks user info against an eligibility file if configured for the current account. The user will receive an email with an activation code.

Parameters:
- X-AccountCode (header, string, required) — Account code

Request body (application/x-www-form-urlencoded):
- first_name (string, required)
- last_name (string, required)
- email (string, required)
- dob (string, optional) — Date of birth (YYYY-MM-DD)
- ssn (string, optional) — Last 4 digits of SSN

Example request:
```json
{
  "first_name": "An",
  "last_name": "Nguyen",
  "email": "an@vseeclinic.com"
}
```

Responses:
- 200 — Activation email sent
```json
{
  "data": true
}
```
- 400 — Bad Request
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```

## POST /users/login
URL: https://developers.vsee.io/api/user-api/post/users/login
operationId: loginUser
Auth: Account Code Only — Only requires the X-AccountCode header. No token needed.

Login

Log user in and retrieve access token. **Public access** — no API token required.

Two login methods:
1. **Active user**: Use `username` and `password`
2. **Inactive user** (no password set): Use `email` and `email_token` sent to their email

After updating password via API, inactive users can use the active login method.

Parameters:
- X-AccountCode (header, string, required) — Account code

Request body (application/x-www-form-urlencoded):
- username (string, optional) — For active user login
- password (string, optional) — For active user login
- email (string, optional) — For inactive user login
- email_token (string, optional) — For inactive user login (token sent to email)

Example request:
```json
{
  "username": "member-201",
  "password": "example_password"
}
```

Responses:
- 200 — Successful login
```json
{
  "data": {
    "user_id": "201",
    "token": "18c31fa10afb6f0857c803eb01a2b392",
    "expiry": 1473822319,
    "created": 1473735919,
    "user_type": "200",
    "refresh_token": {
      "user_id": "201",
      "token": "6338a6e42f407acf39d07a63442efb9d",
      "expiry": 1476327919,
      "created": 1473735919
    },
    "user": {
      "id": "201",
      "code": "54bdf165f02c4a0fbaac2603ac1f0144",
      "first_name": "Lemuel",
      "last_name": "Eveline (201)test",
      "username": "member-201",
      "vseeid": "conciergedev+richard",
      "dob": "1960-01-01",
      "email": "an+user1@vsee.com",
      "gender": 2,
      "active": true,
      "tos": false,
      "phone": "800-555-5555",
      "subtype": ""
    }
  }
}
```
- 400 — Bad Request
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```
- 401 — Unauthorized
```json
{
  "code": 404,
  "message": "Sorry, this page is not available."
}
```