{ "openapi": "3.0.3", "info": { "title": "VSee Clinic User API", "description": "The VSee Clinic User API allows developers to manage users, authentication, and profiles\nwithin the VSee Clinic platform.\n\n\n### User Types\n| Value | Meaning | Description |\n|-------|---------|-------------|\n| 100 | Admin | Admin user |\n| 200 | Member | A registered patient |\n| 300 | Company | Company user |\n| 400 | Provider | Physician or CSR |\n| 500 | Kiosk | Deprecated |\n| 600 | Guest | Guest one-time user |\n| 700 | Phone Bridge | User joined by dial-in |\n\n### Provider Subtypes\n| Value | Meaning |\n|-------|---------|\n| 460 | Medical Assistant |\n| 470 | CSR (Customer Service Representative) |\n| 480 | Paramedic / Remote Medic |\n| 482 | Doctor / Licensed Service Provider |\n| 484 | Nurse / Remote Medic |\n", "version": "3.0", "contact": { "email": "admin@vsee.com" } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": false, "samples-languages": [ "curl", "python", "javascript", "java" ] }, "servers": [ { "url": "https://api.vseepreview.com/api_v3", "description": "Staging" } ], "components": { "securitySchemes": { "ApiToken": { "type": "apiKey", "in": "header", "name": "X-ApiToken", "description": "User access token obtained from login or SSO" }, "ApiKey": { "type": "apiKey", "in": "header", "name": "X-ApiKey", "description": "API Key generated under Developers menu" }, "ApiSecret": { "type": "apiKey", "in": "header", "name": "X-ApiSecret", "description": "API Secret generated under Developers menu" } }, "parameters": { "AccountCode": { "name": "X-AccountCode", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your VSee Clinic Account Code", "example": "vclinic" } }, "schemas": { "UserType": { "type": "integer", "enum": [ 100, 110, 140, 150, 160, 200, 300, 400, 500, 600, 700 ], "description": "User type:\n- `100` - Admin\n- `110` - Cronjob (system)\n- `140` - System\n- `150` - Common Admin\n- `160` - API (system)\n- `200` - Member (registered patient)\n- `300` - Company\n- `400` - Provider (Physician or CSR)\n- `500` - Kiosk (deprecated)\n- `600` - Guest (one-time user)\n- `700` - Phone Bridge (dial-in user)\n" }, "UserSubtype": { "type": "integer", "enum": [ 460, 470, 480, 482, 484, 486 ], "description": "Provider subtype:\n- `460` - Medical Assistant\n- `470` - CSR\n- `480` - Paramedic (Remote Medic)\n- `482` - Doctor (Licensed Service Provider)\n- `484` - Nurse (Remote Medic)\n- `486` - SNF Nurse (deprecated)\n" }, "UserSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "20008869839" }, "email": { "type": "string", "example": "anton+patient1@vseelab.com" }, "full_name": { "type": "string", "example": "Anton Patient1" } } }, "UserProfile": { "type": "object", "properties": { "id": { "type": "string", "example": "27769243" }, "code": { "type": "string", "example": "63f67706de344db98a6461d00adc646e" }, "first_name": { "type": "string", "example": "anton" }, "last_name": { "type": "string", "example": "test_2" }, "full_name": { "type": "string", "example": "anton test_2" }, "username": { "type": "string", "example": "anton+test2@vseelab.com" }, "vseeid": { "type": "string", "example": "cmo+user27769243" }, "dob": { "type": "string", "format": "date", "example": "1980-01-01" }, "email": { "type": "string", "example": "anton+test2@vseelab.com" }, "gender": { "type": "integer", "example": 1 }, "active": { "type": "boolean", "example": true }, "tos": { "type": "boolean", "example": true }, "status": { "type": "integer", "example": 20 }, "subtype": { "type": "string", "example": "" }, "timezone": { "type": "string", "example": "Europe/Berlin" }, "email_verified": { "type": "boolean", "example": true }, "signup_step": { "type": "integer", "example": 99 }, "extra": { "type": "object", "properties": { "marital_status": { "type": "string" }, "gender_identity": { "type": "string" }, "social_security_no": { "type": "string" }, "veteran": { "type": "string" }, "race": { "type": "string" }, "ethnicity": { "type": "string" }, "health_insurance": { "type": "string" }, "insurance": { "type": "string" }, "insurance_policy_number": { "type": "string" }, "attachments": { "type": "string", "nullable": true }, "emerg_contact_name": { "type": "string" } } }, "account_code": { "type": "string", "example": "vclinic" }, "clinics": { "type": "array", "items": { "type": "string" }, "example": [ "vclinic" ] }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "account_code": { "type": "string" }, "domain": { "type": "string" }, "default": { "type": "boolean" }, "added_time": { "type": "integer" }, "source": { "type": "string" } } } }, "created": { "type": "integer", "example": 1677096710 }, "type": { "type": "integer", "example": 200 } } }, "TokenResponse": { "type": "object", "properties": { "user_id": { "type": "string", "example": "10008" }, "token": { "type": "string", "example": "0437c1ce3b7079906e2ff247aad1adda" }, "expiry": { "type": "integer", "example": 1473821786 }, "refresh_token": { "type": "object", "properties": { "user_id": { "type": "string", "example": "10008" }, "token": { "type": "string", "example": "2693615fd2a46edf13334b3f35580e26" }, "expiry": { "type": "integer", "example": 1476327386 }, "created": { "type": "integer", "example": 1473735386 } } } } }, "SsoUserResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "10008" }, "code": { "type": "string", "example": "57d76ada0bb444f9b3057855ac1f0144" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "username": { "type": "string", "example": "57d76ad979b843e6973e7855ac1f0144" }, "vseeid": { "type": "string", "example": "conciergedev+57d76ad979b843e6973e7855ac1f0144" }, "dob": { "type": "string", "example": "1990-01-01" }, "active": { "type": "boolean", "example": true }, "tos": { "type": "boolean", "example": false }, "subtype": { "type": "string", "example": "" }, "token": { "$ref": "#/components/schemas/TokenResponse" } } }, "LoginResponse": { "type": "object", "properties": { "user_id": { "type": "string", "example": "201" }, "token": { "type": "string", "example": "18c31fa10afb6f0857c803eb01a2b392" }, "expiry": { "type": "integer", "example": 1473822319 }, "created": { "type": "integer", "example": 1473735919 }, "user_type": { "type": "string", "example": "200" }, "refresh_token": { "type": "object", "properties": { "user_id": { "type": "string" }, "token": { "type": "string" }, "expiry": { "type": "integer" }, "created": { "type": "integer" } } }, "user": { "$ref": "#/components/schemas/UserProfile" } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Sorry, this page is not available." } } } }, "responses": { "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "paths": { "/users": { "get": { "tags": [ "Users" ], "summary": "List users", "description": "Retrieve a list of users with optional filtering and sorting.\n\n**Tip:** Wherever there's a user `:id` field in API methods, it also accepts dash (`-`) as a mapping to the current user.", "operationId": "getUsers", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "query", "description": "Filter by user ID(s). Accepts single ID, comma-separated string, or array. E.g: `123` or `\"1234,1235\"` or `[1234, 1235]`", "schema": { "type": "string" }, "example": "123" }, { "name": "full_name", "in": "query", "description": "Full text search by name (minimum 3 characters)", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Like search by email (minimum 3 characters)", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Search keyword (minimum 3 chars). Searches `full_name` and `email`. Should be used in conjunction with `type`.", "schema": { "type": "string" }, "example": "anton+patient1@vseelab.com" }, { "name": "type", "in": "query", "description": "User type. E.g: `400` or `\"200,600\"`. Types: 100=Admin, 200=Member, 400=Provider, 600=Guest", "schema": { "type": "string" }, "example": "200" }, { "name": "status", "in": "query", "description": "User status. Accepts single value, comma-separated, or array. E.g: `20` or `\"10,20\"`", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Filter by role. E.g: `\"clinic_admin\"` or `\"clinic_admin,scheduler\"`", "schema": { "type": "string" } }, { "name": "ex_filter", "in": "query", "description": "Extended filter: `all` (filter by assigned rooms) or `my-patient` (filter by own visits)", "schema": { "type": "string", "enum": [ "all", "my-patient" ] } }, { "name": "is_hidden", "in": "query", "description": "Hide/Unhide patient from patient list (RPM feature)", "schema": { "type": "boolean" } }, { "name": "is_admin", "in": "query", "schema": { "type": "boolean" }, "description": "Filter admin users" }, { "name": "room_code", "in": "query", "schema": { "type": "string" }, "description": "Filter by room code" }, { "name": "account_code", "in": "query", "schema": { "type": "string" } }, { "name": "group", "in": "query", "description": "Filter by clinic group", "schema": { "type": "string" } }, { "name": "subtype", "in": "query", "description": "Provider sub type. Values: 480=Paramedic, 482=Doctor, 484=Nurse, 470=CSR, 460=Medical Assistant", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort order. E.g: `\"full_name.asc\"` or `{full_name: \"asc\"}`", "schema": { "type": "string" }, "example": "full_name.asc" }, { "name": "start", "in": "query", "description": "Offset for pagination", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "Page size for pagination", "schema": { "type": "integer", "default": 20 } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return. Available: `id`, `username`, `first_name`, `last_name`, `full_name`, `last_login`, `type`, `subtype`", "schema": { "type": "string" }, "example": "username,full_name,last_login" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserSummary" } }, "total_count": { "type": "integer", "example": 500 } } }, "examples": { "List members (type=200)": { "summary": "List all members (patients)", "value": { "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 } }, "List providers (type=400)": { "summary": "List all providers", "value": { "data": [ { "email": "doctor+1@vseelab.com", "id": "20008870001", "full_name": "Dr. Jane Smith" }, { "email": "doctor+2@vseelab.com", "id": "20008870002", "full_name": "Dr. John Doe" } ], "total_count": 25 } }, "Search by email": { "summary": "Filter users by email with type", "value": { "data": [ { "email": "anton+patient1@vseelab.com", "id": "20008869839", "full_name": "Anton Patient1" } ], "total_count": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Missing account code": { "summary": "Missing account code", "value": { "code": 400, "message": "Missing required header: X-AccountCode" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Unauthorized": { "summary": "Invalid or missing API key", "value": { "code": 401, "message": "Unauthorized" } } } } } } }, "x-auth-type": "admin-token" } }, "/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get user by ID", "description": "Get profile data of a particular user, including fields from the extended profile (if any).\n\n**Tip:** The `:id` parameter also accepts dash (`-`) to refer to the current authenticated user.\n\nReturns the full profile including extended profile fields, rooms, clinics, and account info.", "operationId": "getUserById", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "path", "required": true, "description": "User ID, or `-` for the current user", "schema": { "type": "string" }, "example": "27769243" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserProfile" } } }, "examples": { "Get user profile": { "summary": "Full user profile with extended fields", "value": { "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": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Unauthorized": { "summary": "Invalid API key", "value": { "code": 401, "message": "Unauthorized" } } } } } }, "404": { "$ref": "#/components/responses/NotFound", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "User not found": { "summary": "User not found", "value": { "code": 404, "message": "User not found" } } } } } } }, "x-auth-type": "user-token" } }, "/users/sso": { "post": { "tags": [ "Authentication" ], "summary": "Single Sign On (SSO)", "description": "Single Sign On for patient and provider. This is disabled by default \u2014 contact admin@vsee.com to request it.\n\nSSO 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.\n\nUse `?fields=vsee` to include VSee ID and token in the response (for Browser Call SDK workflow).\n\n**Important:** SSO is disabled by default. Contact admin@vsee.com to request activation.\n\nSSO creates a user record on VSee side on first call and returns the existing user for subsequent requests using the same `code`.\n\n**Tip:** Use `POST /users/sso?fields=vsee` to include the VSee ID and token in the response for Browser Call SDK workflow.\n\n### E-Prescribe Requirements\nTo enable e-prescribing for a patient (type=200), the following additional fields are **required** in the SSO call:\n- `gender` (string): `male` or `female`\n- `street_addr` (string): Patient's street address\n- `city` (string): Patient's city\n- `state` (string): Two-letter state abbreviation\n- `zip` (string): ZIP code\n- `phone` (string): Phone number\n- `dob` (string): Date of birth in YYYY-MM-DD format\n\n### SSO Types\n- **Guest SSO** (type=600): Creates a one-time guest user. No `code` required.\n- **Patient SSO** (type=200): Creates/returns a registered patient. `code` is required (max 128 chars).\n- **Provider SSO** (type=400): Creates/returns a provider. `code` is required (max 128 chars).\n\n### Response Token\nUse `data.token.token` to redirect user to VSee Clinic portal via the `/auth` endpoint.", "operationId": "ssoUser", "parameters": [ { "name": "X-ApiKey", "in": "header", "description": "API Key", "required": true, "schema": { "type": "string" }, "example": "your_api_key" }, { "name": "X-ApiSecret", "in": "header", "description": "API Secret", "required": true, "schema": { "type": "string" }, "example": "your_api_secret" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "fields", "in": "query", "description": "Include additional fields in response. Use `vsee` to get VSee ID and token for Browser Call SDK.", "schema": { "type": "string", "enum": [ "vsee" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "first_name", "last_name", "type" ], "properties": { "first_name": { "type": "string", "description": "User's first name", "example": "John" }, "last_name": { "type": "string", "description": "User's last name", "example": "Smith" }, "type": { "type": "integer", "description": "User type: 200 (Member/Patient), 400 (Provider), 600 (Guest)", "enum": [ 200, 400, 600 ], "example": 200 }, "code": { "type": "string", "description": "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.", "example": "mypatient_uuid1234-5678-90", "maxLength": 128 }, "dob": { "type": "string", "description": "Date of birth in YYYY-MM-DD format", "example": "1990-01-01" }, "email": { "type": "string", "description": "User email address", "example": "john.smith@example.com" }, "username": { "type": "string", "description": "Optional \u2014 system will generate one as fallback" }, "disable_emails": { "type": "integer", "description": "Set to `1` to disable all email notifications", "enum": [ 0, 1 ] }, "gender": { "type": "string", "description": "Required for e-prescribe. `male` or `female`", "enum": [ "male", "female" ] }, "street_addr": { "type": "string", "description": "Required for e-prescribe" }, "city": { "type": "string", "description": "Required for e-prescribe" }, "state": { "type": "string", "description": "Required for e-prescribe. Two-letter state abbreviation", "example": "CA" }, "zip": { "type": "string", "description": "Required for e-prescribe", "example": "94105" }, "phone": { "type": "string", "description": "Required for e-prescribe", "example": "800-555-5555" } } }, "examples": { "Guest SSO": { "summary": "Guest SSO (type 600)", "value": { "first_name": "John", "last_name": "Smith", "type": 600 } }, "Patient SSO": { "summary": "Patient SSO (type 200)", "value": { "first_name": "John", "last_name": "Smith", "code": "mypatient_uuid1234-5678-90", "email": "john.smith@example.com", "type": 200 } }, "Provider SSO": { "summary": "Provider SSO (type 400)", "value": { "first_name": "John", "last_name": "Provider", "code": "myprovider_uuid1234-5678-90", "email": "john.provider@example.com", "type": 400 } } } } } }, "responses": { "200": { "description": "Successful SSO response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SsoUserResponse" } } }, "examples": { "Guest SSO": { "summary": "Guest SSO response", "value": { "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 } } } } }, "Patient SSO": { "summary": "Patient SSO response", "value": { "data": { "id": "10008", "code": "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb", "first_name": "John", "last_name": "Smith", "username": "57d76ad979b843e6973e7855ac1f0144", "vseeid": "conciergedev+57d76ad979b843e6973e7855ac1f0144", "active": true, "tos": false, "subtype": "", "token": { "user_id": "10008", "token": "0437c1ce3b7079906e2ff247aad1adda", "expiry": 1473821786, "refresh_token": { "user_id": "10008", "token": "2693615fd2a46edf13334b3f35580e26", "expiry": 1476327386, "created": 1473735386 } } } } }, "Provider SSO": { "summary": "Provider SSO response", "value": { "data": { "id": "10008", "code": "cd978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb", "first_name": "John", "last_name": "Provider", "username": "57d76ad979b843e6973e7855ac1f0144", "vseeid": "anton+johnsmithprovider@vseelab.com", "email": "anton+johnsmithprovider@vseelab.com", "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": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Missing member ID": { "summary": "Missing required field", "value": { "code": 400, "message": "member_id is required" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Invalid API credentials": { "summary": "Invalid API credentials", "value": { "code": 401, "message": "Unauthorized" } } } } } } }, "x-auth-type": "api-key-secret" } }, "/auth": { "get": { "tags": [ "Authentication" ], "summary": "SSO redirect login", "description": "Use this URL to redirect a user to VSee Clinic with automatic login.\n\nPattern: `https://{portal_url}/auth?sso_token={token}&next={next_url}`\n\nThis will log the user in and redirect them to the specified URL path.", "operationId": "authRedirect", "parameters": [ { "name": "sso_token", "in": "query", "required": true, "description": "SSO token from the POST /users/sso response", "schema": { "type": "string" }, "example": "66bcd0acff324e8a44992d9596b5d361" }, { "name": "next", "in": "query", "description": "URL path to redirect the user to after login", "schema": { "type": "string" }, "example": "/u/clinic" }, { "name": "one_time_token", "in": "query", "description": "Set to `1` to invalidate the sso_token after login (additional security)", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "disable_navigation", "in": "query", "description": "Set to `1` to disable all email communication", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "302": { "description": "Redirects user to VSee Clinic portal" } }, "x-auth-type": "none" } }, "/me": { "get": { "tags": [ "Users" ], "summary": "Get current user profile", "description": "Retrieve the profile of the currently authenticated user.", "operationId": "getMe", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "user_photo_size", "in": "query", "description": "User photo dimensions in WxH format (e.g. `320x240`)", "schema": { "type": "string" }, "example": "320x240" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserProfile" } } }, "examples": { "Current user profile": { "summary": "Authenticated user profile", "value": { "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": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Unauthorized": { "summary": "Token expired or invalid", "value": { "code": 401, "message": "Unauthorized" } } } } } } }, "x-auth-type": "user-token" }, "post": { "tags": [ "Users" ], "summary": "Update current user profile", "description": "Update the profile of the currently authenticated user.", "operationId": "updateMe", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "password": { "type": "string", "description": "Send alone for first-time password set, or with old_password to change it" }, "old_password": { "type": "string", "description": "Required when changing password" }, "dob": { "type": "string", "description": "Date of birth (YYYY-MM-DD)", "example": "1983-10-02" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "nationality": { "type": "string", "example": "Vietnamese" }, "tos": { "type": "integer", "description": "0 - not accepted, 1 - accepted Terms of Service", "enum": [ 0, 1 ] }, "phone": { "type": "string" }, "street_addr": { "type": "string" }, "state": { "type": "string", "description": "2-letter state code", "example": "CA" }, "zip": { "type": "string", "example": "07123" }, "city": { "type": "string" }, "pcp_name": { "type": "string", "description": "Primary Care Physician Name" }, "pcp_phone": { "type": "string", "description": "Primary Care Physician Phone (10 digits)" }, "timezone": { "type": "string", "description": "Timezone string (e.g. `America/New_York`, `Asia/Tokyo`)", "example": "America/New_York" }, "photo": { "type": "string", "description": "File ID from POST /files API. Pass empty string to delete avatar." } } }, "examples": { "Update profile": { "summary": "Update password, DOB, and nationality", "value": { "password": "example_password", "dob": "1983-10-02", "nationality": "Vietnamese" } }, "Set first password": { "summary": "First-time password setup", "value": { "password": "newSecurePassword123" } }, "Change password": { "summary": "Change existing password", "value": { "old_password": "currentPassword", "password": "newSecurePassword123" } } } } } }, "responses": { "200": { "description": "Successful update", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserProfile" } } }, "examples": { "Update profile": { "summary": "Profile updated", "value": { "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 } } }, "Set first password": { "summary": "Password set successfully", "value": { "data": { "id": "201", "first_name": "An", "last_name": "Nguyen", "active": true } } }, "Change password": { "summary": "Password changed", "value": { "data": { "id": "201", "first_name": "An", "last_name": "Nguyen", "active": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Invalid field": { "summary": "Invalid field value", "value": { "code": 400, "message": "Invalid value for field: phone" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Unauthorized": { "summary": "Token expired", "value": { "code": 401, "message": "Unauthorized" } } } } } } }, "x-auth-type": "user-token" } }, "/users/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout", "description": "Log the current user session out. The supplied tokens will be destroyed.", "operationId": "logoutUser", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "tokens": { "type": "string", "description": "Comma-separated tokens to destroy, e.g. `token1,token2`" } } }, "examples": { "Logout": { "summary": "Destroy session tokens", "value": { "tokens": "token1,token2" } } } } } }, "responses": { "200": { "description": "Successful logout", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "boolean", "example": true } } }, "examples": { "Logout": { "summary": "Successful logout", "value": { "data": true } } } } } } }, "x-auth-type": "user-token" } }, "/tokens/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Refresh access token", "description": "Use a refresh token to generate a new access token. A new refresh token is also returned for the next refresh.", "operationId": "refreshToken", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string", "description": "The refresh token from a previous login or refresh response", "example": "6366a7018a39536a1ef4b63626f8e734" } } }, "examples": { "Refresh token": { "summary": "Refresh an expiring token", "value": { "refresh_token": "6366a7018a39536a1ef4b63626f8e734" } } } } } }, "responses": { "200": { "description": "New token pair", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "string" }, "user_type": { "type": "string" }, "token": { "type": "string" }, "expiry": { "type": "integer" }, "user": { "$ref": "#/components/schemas/UserProfile" } } } } }, "examples": { "Refresh token": { "summary": "New token pair returned", "value": { "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": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Expired token": { "summary": "Token already expired", "value": { "code": 401, "message": "Token has expired and cannot be refreshed" } } } } } } }, "x-auth-type": "account-code-only" } }, "/users/reset_password": { "post": { "tags": [ "Authentication" ], "summary": "Reset password", "description": "Send a reset password email to the supplied email address if valid.", "operationId": "resetPassword", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Valid email to send reset password email", "example": "an+1@vsee.com" } } }, "examples": { "Reset password": { "summary": "Send reset password email", "value": { "email": "an+1@vsee.com" } } } } } }, "responses": { "200": { "description": "Reset email sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "boolean", "example": true } } }, "examples": { "Reset password": { "summary": "Reset email sent", "value": { "data": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "User not found": { "summary": "No matching user", "value": { "code": 400, "message": "No user found with that email address" } } } } } } }, "x-auth-type": "account-code-only" } }, "/users/alive": { "post": { "tags": [ "Users" ], "summary": "Keep alive", "description": "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.\n\nSend at an interval less than 1/2 of the heartbeat value. Only \"alive\" patients show up on the provider dashboard.", "operationId": "keepAlive", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "heartbeat": { "type": "integer", "description": "Custom heartbeat value in seconds (default: 300s). For mobile, set to ~300s and update every ~250s.", "default": 300, "example": 300 } } }, "examples": { "Keep alive": { "summary": "Send heartbeat ping", "value": { "heartbeat": 300 } } } } } }, "responses": { "200": { "description": "Heartbeat acknowledged", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "last_connected": { "type": "integer", "example": 1423023124 }, "heartbeat": { "type": "integer", "example": 300 } } } } }, "examples": { "Keep alive": { "summary": "Heartbeat acknowledged", "value": { "data": { "last_connected": 1423023124, "heartbeat": 300 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Invalid session": { "summary": "Invalid or expired session", "value": { "code": 401, "message": "Unauthorized" } } } } } } }, "x-auth-type": "user-token" } }, "/users/activate": { "post": { "tags": [ "Authentication" ], "summary": "Activate user", "description": "Checks user info against an eligibility file if configured for the current account. The user will receive an email with an activation code.", "operationId": "activateUser", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "first_name", "last_name", "email" ], "properties": { "first_name": { "type": "string", "example": "An" }, "last_name": { "type": "string", "example": "Nguyen" }, "email": { "type": "string", "example": "an@vseeclinic.com" }, "dob": { "type": "string", "description": "Date of birth (YYYY-MM-DD)", "example": "1988-10-02" }, "ssn": { "type": "string", "description": "Last 4 digits of SSN", "example": "1234" } } }, "examples": { "Activate user": { "summary": "Activate with basic info", "value": { "first_name": "An", "last_name": "Nguyen", "email": "an@vseeclinic.com" } }, "Activate with eligibility": { "summary": "Activate with DOB and SSN for eligibility check", "value": { "first_name": "An", "last_name": "Nguyen", "email": "an@vseeclinic.com", "dob": "1988-10-02", "ssn": "1234" } } } } } }, "responses": { "200": { "description": "Activation email sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "boolean", "example": true } } }, "examples": { "Activate user": { "summary": "Activation email sent", "value": { "data": true } }, "Activate with eligibility": { "summary": "Activation email sent after eligibility check", "value": { "data": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Invalid activation code": { "summary": "Invalid or expired code", "value": { "code": 400, "message": "Invalid or expired activation code" } } } } } } }, "x-auth-type": "account-code-only" } }, "/users/login": { "post": { "tags": [ "Authentication" ], "summary": "Login", "description": "Log user in and retrieve access token. **Public access** \u2014 no API token required.\n\nTwo login methods:\n1. **Active user**: Use `username` and `password`\n2. **Inactive user** (no password set): Use `email` and `email_token` sent to their email\n\nAfter updating password via API, inactive users can use the active login method.", "operationId": "loginUser", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "For active user login", "example": "member-201" }, "password": { "type": "string", "description": "For active user login", "example": "111111" }, "email": { "type": "string", "description": "For inactive user login" }, "email_token": { "type": "string", "description": "For inactive user login (token sent to email)" } } }, "examples": { "Active user login": { "summary": "Login with username and password", "value": { "username": "member-201", "password": "example_password" } }, "Inactive user login": { "summary": "Login with email token (inactive user)", "value": { "email": "an+1@vsee.com", "email_token": "ztpand" } } } } } }, "responses": { "200": { "description": "Successful login", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LoginResponse" } } }, "examples": { "Active user login": { "summary": "Successful login response", "value": { "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": "" } } } }, "Inactive user login": { "summary": "Successful login with email token", "value": { "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", "first_name": "An", "last_name": "Nguyen", "email": "an+1@vsee.com", "active": false } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Missing credentials": { "summary": "Missing username or password", "value": { "code": 400, "message": "Username and password are required" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Wrong password": { "summary": "Invalid credentials", "value": { "code": 401, "message": "Invalid username or password" } } } } } } }, "x-auth-type": "account-code-only" } } } }