# VSee Clinic API — Full Documentation > Complete documentation corpus for the VSee Clinic telehealth API. Authentication uses custom headers (X-ApiToken, X-AccountCode, X-ApiKey, X-ApiSecret), not Bearer tokens. Staging base URL: https://api.vseepreview.com/api_v3 Site: https://developers.vsee.io · Index: https://developers.vsee.io/llms.txt # Guides ## Getting Started URL: https://developers.vsee.io/guides/getting-started ### Getting Started Everything you need to set up and start integrating with the VSee Clinic API. ### Environments VSee provides two separate environments. Each has its own domain, credentials, and data. Tokens from one environment will not work in the other. Staging (Test) Clinic URLhttps://yourcode.vseepreview.com API Base URLhttps://api.vseepreview.com/api_v3 Production (Live) Clinic URLhttps://yourcode.vsee.me API Base URLhttps://api.vsee.me/api_v3 Important: Staging and production are completely separate. Your staging Account Code, API tokens, and API Key/Secret will not work in production, and vice versa. Always verify you're using the correct base URL and credentials for your target environment. ### Sign Up for a Developer Account To start building with the VSee Clinic API, you'll need a developer account. This gives you a staging clinic with API credentials to develop and test your integration. Create Developer AccountSign Up Instructions ### Configure Your Credentials Enter your API credentials below. They'll be saved in your browser and auto-populated across all use cases and the Try It feature, so you don't have to re-enter them for every request. No credentials configured Show values Clinic URL Your clinic's base URL for redirects X-AccountCode X-ApiKey X-ApiSecret X-ApiToken Clinic Admin API Token from dashboard Admin Token Room Slug Waiting room slug used in redirect URLs Room Code Waiting room code used in API requests Provider ID ID of the provider handling visits (from Provider SSO data.id) Credentials are stored in your browser's sessionStorage (cleared when you close the tab) and never sent to our servers. Save Credentials ### Onboarding Checklist 1Get a Developer AccountSign up for a developer account to get a staging clinic with API access. See the sign up instructions for a detailed walkthrough. 2Receive Staging ClinicYou'll be assigned a staging clinic at yourcode.vseepreview.com. 3Obtain API CredentialsGet your Account Code, API Key/Secret (for SSO), and Clinic Admin API Token from the staging admin dashboard. 4Build and Test in StagingDevelop your integration against the staging API. All test data stays in the staging environment. 5Request Production AccessWhen your integration is tested and ready, request production credentials for your live clinic. ### Quick Start Example Here's a simple test to verify your credentials. This calls the Settings API, which only requires an Account Code: curl -X GET https://api.vseepreview.com/api_v3/settings \ -H "X-AccountCode: YOUR_ACCOUNT_CODE" If you get a JSON response with clinic settings, your Account Code is valid and you're connected to the right environment. ### Browse & Download OpenAPI Specs All 16 APIs are published as OpenAPI 3.0 specifications. Browse the full list and download any spec as raw JSON — ready to import into Postman, Swagger, or AI tools. Browse OpenAPI Specs ### CORS & Browser Requests The VSee API does not support CORS for direct browser-to-API calls. You cannot call the API directly from frontend JavaScript running in a browser. If you're building a web application, all API calls must be routed through your backend server. Your server-side code makes the API call, then returns the result to your frontend. Browser Your Web App Server Your Backend API VSee API ### Common Mistakes I'm getting a 403 "Bad Request" error This usually means you're using the wrong token type for this endpoint. For admin operations (creating rooms, managing webhooks, etc.), you need the Clinic Admin API Token from the dashboard — not a user session token from login/SSO. I'm getting "Unauthorized Access" Your token may be expired, invalid, or from the wrong environment. Check that: (1) your token hasn't expired, (2) you're using staging tokens with the staging URL and production tokens with the production URL, and (3) your Account Code matches the environment. I'm getting a CORS error in the browser The VSee API does not support CORS. You must route all API calls through your backend server. Direct browser-to-API calls will always fail with a CORS error. What's the difference between vseepreview.com and vsee.me? vseepreview.com is the staging (test) environment and vsee.me is production (live). They're completely separate — different data, different credentials. Always develop and test in staging first. Why do I have two different tokens? Your clinic has a Clinic Admin API Token (for server-side admin operations) and user session tokens (returned when users log in). They serve different purposes and have different permissions. See the Authentication Guide for details. ## Authentication URL: https://developers.vsee.io/guides/auth-guide ### Authentication Guide Learn how to authenticate with the VSee Clinic API. Different endpoints require different credentials. ### Overview The VSee Clinic API uses header-based authentication. Every request must include an X-AccountCode header to identify your clinic. Depending on the endpoint, you'll also need one of several token types. Common mistake: Using an SSO access token or user login token to call admin endpoints (like Create Room). Admin endpoints require the Clinic Admin API Token from your dashboard, not a user session token. ### Token Types Token Type | How to Get It | Header(s) | When to Use Clinic Admin API Token | Admin Dashboard → Developers → App → Edit App | X-ApiToken + X-AccountCode | Server-to-server admin operations: creating rooms, managing users, account settings, webhooks, recordings User Access Token | Response from POST /users/login or POST /users/sso | X-ApiToken + X-AccountCode | Acting on behalf of a logged-in user: get/update profile, visits, EMR, logout API Key + Secret | Issued during API access onboarding | X-ApiKey + X-ApiSecret + X-AccountCode | SSO endpoints only (POST /users/sso) Account Code Only | Issued during onboarding | X-AccountCode | Public/pre-login endpoints: login, activate user, reset password, settings None | N/A | — | A few endpoints require no auth headers (e.g., GET /auth) ### Clinic Admin Token vs User Token Both the Clinic Admin API Token and User Access Token are sent in the same X-ApiToken header, but they are different values with different permissions: Clinic Admin API Token - • Generated in the Admin Dashboard under Developers → App → Edit App - • Does not expire (until regenerated) - • Has full admin permissions for your clinic - • Used for server-to-server integrations - • Never expose in client-side code User Access Token - • Returned from login or SSO endpoints - • Expires after a period of inactivity - • Scoped to the authenticated user's permissions - • Used for user-facing actions - • Can be refreshed with POST /users/token/refresh ### Which Token Do I Need? 1Are you calling the SSO endpoint? → Use API Key + Secret 2Are you managing clinic resources (rooms, webhooks, recordings, account settings)? → Use Clinic Admin API Token 3Are you doing something on behalf of a logged-in user? → Use User Access Token 4Are you calling a public/pre-login endpoint (login, settings, activate)? → Use Account Code only ### Auth Badges in This Documentation Each endpoint in the API Reference displays a colored badge indicating which authentication method it requires: Admin TokenUser TokenAPI Key + SecretAccount Code OnlyNo Auth ### Example: Creating a Room (Admin Token) This is one of the most common integration points. Notice the X-ApiToken value here must be the Clinic Admin API Token from your dashboard — not a user session token. curl -X POST https://api.vsee.me/api_v3/rooms \ -H "X-AccountCode: YOUR_CLINIC_CODE" \ -H "X-ApiToken: YOUR_CLINIC_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Patient Consultation", "members": ["doctor@example.com"] }' ## Error Reference URL: https://developers.vsee.io/guides/error-reference ### Error Reference Common API error responses and how to fix them. ### HTTP Status Codes The VSee API uses standard HTTP status codes. Here are the most common ones you'll encounter: Status | Meaning | What to Do 200 | Request succeeded. | N/A — success! 400 | Missing required fields or invalid parameters. | Check your request body and query parameters. Ensure all required fields are included. 401 | Authentication failed. | Check your token is valid, not expired, and for the correct environment. 403 | You don't have permission for this action. | You may be using the wrong token type. Admin endpoints require the Clinic Admin API Token. 404 | The resource or endpoint doesn't exist. | Verify the URL path and any ID parameters. Check that you're using the correct base URL. 422 | Validation failed on the request data. | Check field formats, required fields, and data types match the spec. 429 | Too many requests. | Slow down your request rate. Implement exponential backoff. 500 | Something went wrong on the server. | Retry after a brief delay. If persistent, contact VSee support. ### Common Error Scenarios 403403 Bad Request — Wrong Token Type { "code": "85FBEFE5", "message": "Bad Request" } Cause: You're using a user session token (from login/SSO) on an endpoint that requires the Clinic Admin API Token. Fix: Use the Clinic Admin API Token from your admin dashboard (Developers → App → Edit App) instead of a user session token. This is the most common error when integrating the Rooms API, Webhooks, or Recordings API. 401401 Unauthorized — Invalid or Expired Token { "message": "Unauthorized Access" } Cause: Your token is invalid, expired, or from the wrong environment (e.g., staging token used against production). Fix: Re-authenticate to get a fresh token. Verify you're using the correct base URL for your environment (api.vseepreview.com for staging, api.vsee.me for production). 400400 Bad Request — Missing Required Field { "message": "Bad Request", "errors": { "title": "The title field is required" } } Cause: A required parameter or body field is missing from your request. Fix: Check the endpoint's parameter documentation. Ensure all required fields are present in your request body and headers. 0CORS Error (Browser) Access to fetch at 'https://api.vsee.me/...' has been blocked by CORS policy Cause: You're calling the API directly from browser-side JavaScript. Fix: The VSee API does not support CORS. Route all API calls through your backend server. See the Getting Started guide for the recommended architecture. 403403 Forbidden — Environment Mismatch { "message": "Bad Request" } Cause: You're using staging credentials against production (or vice versa), or the account code doesn't match the base URL. Fix: Ensure all of these match the same environment: base URL, Account Code, API Token, API Key/Secret. Staging uses *.vseepreview.com; production uses *.vsee.me. ### Debugging Tips 1Check the HTTP status code first. It tells you the category of error (auth, validation, server, etc.). 2Read the error message and code. The response body often contains a machine-readable code and human-readable message. 3Test with cURL first. Use the generated cURL command from the API docs to rule out issues with your HTTP library or framework. 4Verify the auth badge. Check the authentication badge on the endpoint you're calling. Make sure you're using the right token type. 5Test in staging first. Always build and test against api.vseepreview.com before moving to production. ### Error Response Format Most error responses follow this format: { "code": "ERROR_CODE", "message": "Human-readable error description" } Some validation errors include an errors object with field-level details: { "message": "Bad Request", "errors": { "field_name": "Description of what's wrong with this field" } } ## Firewall Configuration URL: https://developers.vsee.io/guides/firewall-config - ### Firewall Configuration Port and firewall rules required for VSee services to function correctly. ### Overview VSee services will attempt to navigate network architecture to the best of their ability. However, in order to guarantee the best results, please add the following port and firewall rules to your corporate firewall / router systems. Please note that VSee is not able to provide fixed IP addresses for these servers and they may be switched without prior notification. However, these IP addresses are relatively stationary and any changes will be updated here if they occur. All firewall rules are subject to change with at least 1 month of prior notice. ### Network Security Diagram VSee Security Network Diagram v3.2 ### Simplified Rules If *.vsee.com can be whitelisted, please add this into your firewall rules with the following ports: Purpose | Protocol: Port | Detail Servers VSee Directory, Relay, Call management, Diagnostics, etc.Required for VSee Messenger authentication, address book services, establishing video calls, video packets relay, VSee Messenger chat communication. Measure bandwidth for video quality adjustment. | TCP: 80, 443, 3478, 5222 UDP: 1853, 3478, 6000, 6001, 6256, 10000, 49152 - 65535 (TURN allocated) | *.vsee.com Call presence and reportingUpdate VSee user's status, e.g. Offline, Online, In a call, Busy, etc. | TCP: 443 | vsee-activeapi.firebaseio.com Cloud recording service (Optional, depends on contract)Record video calls performed via VSee Messenger and/or in-browser calls. The calls will be recorded on the server side and will be available via a cloud link. | TCP: 443 | s3.amazonaws.com ### Detailed Rules (US Customers) Please note the servers listed below are for calls within the United States only. If *.vsee.com cannot be whitelisted, the following subdomains and ports are required. ### Messenger Service Purpose | Protocol: Port | Servers | IP Addresses VSee DirectoryAuthentication and address book services for VSee Messenger and in-browser call and chat. | TCP: 5222, 443 | talk.vsee.com xmpp01.vsee.com xmpp02.vsee.com xmpp03.vsee.com xmpp04.vsee.com | 52.52.36.123 52.52.111.88 52.52.245.139 54.215.77.199 US TURN ServersServers that relay packets during video calls in case no direct peer-to-peer connection can be established. | UDP: 3478 TCP: 3478, 443 UDP: 49152 - 65535 (TURN allocated) | cl-coturn.vsee.com cl-coturn-use01.vsee.com cl-coturn-use02.vsee.com cl-coturn-use03.vsee.com cl-coturn-use04.vsee.com cl-coturn-use05.vsee.com cl-coturn-use06.vsee.com cl-coturn-use07.vsee.com cl-coturn-use08.vsee.com cl-coturn-usw01.vsee.com cl-coturn-usw02.vsee.com cl-coturn-usw03.vsee.com cl-coturn-usw04.vsee.com cl-coturn-usw05.vsee.com cl-coturn-usw06.vsee.com cl-coturn-usw07.vsee.com cl-coturn-ohio01.vsee.com cl-coturn-ohio02.vsee.com cl-coturn-oregon01.vsee.com cl-coturn-oregon02.vsee.com | 34.195.60.220 3.91.120.247 18.204.252.34 34.198.123.188 3.94.156.192 44.198.130.26 3.216.83.102 18.213.46.117 52.52.31.136 13.52.175.91 52.9.63.102 54.177.39.6 54.151.95.19 54.215.118.248 52.9.100.25 3.15.110.201 3.14.225.49 34.210.252.42 44.231.34.161 Region Identification ServiceUsed to detect the VSee user's region and to choose the optimal video bridge server for better call performance. | TCP: 443 | region.vsee.com | 54.255.19.27 3.211.169.195 54.177.209.83 Video BridgeDuring a VSee video call, networking packets may pass through a video bridge server for best performance. | TCP: 443 UDP: 10000 | jvb01-ncal.vsee.com jvb02-ncal.vsee.com jvb03-ncal.vsee.com jvb04-ncal.vsee.com jvb05-ncal.vsee.com jvb06-ncal.vsee.com jvb07-ncal.vsee.com jvb08-ncal.vsee.com jvb09-ncal.vsee.com jvb10-ncal.vsee.com jvb01-nvir.vsee.com jvb02-nvir.vsee.com jvb03-nvir.vsee.com jvb04-nvir.vsee.com jvb05-nvir.vsee.com jvb06-nvir.vsee.com jvb07-nvir.vsee.com jvb08-nvir.vsee.com jvb09-nvir.vsee.com jvb10-nvir.vsee.com | 54.151.67.234 54.177.202.54 54.215.26.79 54.219.55.241 184.169.198.132 54.177.84.55 54.67.10.243 54.176.204.219 184.72.28.249 50.18.195.100 35.174.23.28 34.237.10.5 34.232.244.246 18.214.46.241 18.214.51.10 54.242.133.141 54.147.165.97 34.236.235.124 54.204.161.153 174.129.121.60 Messenger update serviceAutomated check for new versions of VSee Messenger. | TCP: 443 | cloudfront.vsee.com | Profile managementManaging VSee user profile, changing password, etc. | TCP: 443 | vsee.com my.vsee.com | 13.248.147.98 76.223.29.204 Messenger diagnosticsDiagnostic information gathered by VSee Messenger. | TCP: 443 | ironmq.vsee.com rtc-stats-v3.vsee.com | 13.248.147.98 76.223.29.204 ### Clinic Service Purpose | Protocol: Port | Servers | IP Addresses Clinic web and API clusterBasic Clinic functionality. | TCP: 443 | *.vsee.me | 99.83.175.218 75.2.83.122 15.197.200.74 3.33.250.220 15.197.231.104 3.33.211.220 Call presence and reportingUpdate VSee users' presence status. | TCP: 443 | vsee-activeapi.firebaseio.com presence.vsee.com conferences.vsee.com | 13.248.147.98 76.223.29.204 ### Optional Firewall Rules Purpose | Protocol: Port | Servers | IP Addresses MFA / SSO (Depends on contract)Enables login with MFA or using an SSO identity provider. | TCP: 443 | auth.vsee.com | See Auth0 IP Allow List Cloud recording (Depends on contract)Record video calls performed via VSee Messenger and/or in-browser calls. The calls will be recorded on the server side and will be available via a cloud link. | TCP: 443 | s3.amazonaws.com | Connectivity Testing ServiceA set of test tools to define if the VSee user's network conditions are good enough for video calls, checking the reachability of critical VSee infrastructure. | TCP: 443 | test.vsee.com | 3.95.130.94 ### Detailed Rules (International Customers) For international customers, please apply all rules in the US Customers section as well as the following: Purpose | Protocol: Port | Detail Servers | IP Addresses International TURN Servers | UDP: 3478 TCP: 3478, 443 UDP: 49152 - 65535 (TURN allocated) | cl-coturn.vsee.com cl-coturn-me01.vsee.com cl-coturn-sg01.vsee.com cl-coturn-sg02.vsee.com cl-coturn-euw01.vsee.com cl-coturn-euc01.vsee.com cl-coturn-euc02.vsee.com | 15.185.164.222 18.138.7.255 18.138.205.235 108.128.27.231 3.65.98.56 18.153.238.27 Video BridgeDuring a VSee video call, networking packets may pass through a video bridge server for best performance. | TCP: 443 UDP: 10000 | jvb01-sg.vsee.com jvb01-eu.vsee.com jvb02-eu.vsee.com | 54.151.243.67 18.156.139.225 54.93.197.61 ### Proxy Servers Many organizations utilize proxy servers with their networks. However, as VSee network traffic is already encrypted, passing this traffic through a proxy server does not make it any more secure. On the other hand, proxy servers can introduce performance problems. Proxy servers can introduce latency and packet loss, which can degrade audio and video quality where real-time streams are essential. Thus, bypassing proxies for VSee traffic is recommended as routing through all traffic through a proxy server might impact connectivity and A/V performance. If proxy servers cannot be bypassed, VSee services can connect to the above hosts via a proxy server. We recommend the following for better performance with a proxy server: - Proxy servers should allow persistent TCP connections. - Proxy servers should be configured to allow UDP traffic to the VSee TURN Servers at port 3478 and the Video Bridges at port 10000 to proceed directly. ### Testing VSee Connectivity VSee provides a suite of tools to help test that firewall rules are configured appropriately. Please note that only a subset of the requirements listed above are tested by these tools. It is important to ensure that the firewall rules listed above are followed, even if these tests pass. Failing to follow the firewall configuration requirements may cause issues such as intermittent bad call quality or dropped calls. Test | URL Basic VSee connectivity | https://test.vsee.com/connectivity TURN connectivity | https://test.vsee.com/turn/ Other tools | https://test.vsee.com/network/index.htmlhttps://clinic.vsee.me/test_computer ### Outbound Connections VSee services may occasionally need to connect with your systems for webhooks and callbacks, or to securely transfer patient / encounter data through SFTP, etc. Here are the lists of IP addresses that should be whitelisted. ### Messenger Service 13.52.171.11352.9.150.124184.72.21.195184.72.47.8354.241.101.173 ### Clinic Service 13.52.7.613.56.46.15952.52.174.23054.177.111.16313.52.58.23718.144.134.16254.241.243.15654.176.136.13113.56.219.5013.56.202.12013.56.70.15550.18.137.25113.52.25.116 ### Updates Feb 10, 2026New - Add in EU coturn and video bridge information Feb 26, 2025- Remove *.pubnub.com from allow list # Use cases ## Patient Dashboard URL: https://developers.vsee.io/use-cases/patient-dashboard Log patient in and take them to VSee Clinic's patient dashboard where they can manage appointments, join video calls, and view visit history. ### Step 1: Obtain patient access token POST /users/sso (auth: API Key + Secret) Call SSO with patient details (type=200). Use ?fields=vsee to include VSee ID and token in the response. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Patient's first name - last_name (required) — Patient's last name - type (required) — User type: 200 = Patient - email — Patient email address - code (required) — Unique patient identifier on your end (max 128 chars) ### Step 2: Redirect to patient dashboard Redirect: https://{your_clinic}.vseepreview.com/auth?sso_token={sso_token}&next=/u/{room_slug} Redirect the patient's browser to the VSee Clinic dashboard. ## Video Session URL: https://developers.vsee.io/use-cases/patient-video-session Log patient in using SSO, create an intake and walk-in visit, then redirect them directly into a video call with a provider. ### Step 1: Obtain patient access token POST /users/sso (auth: API Key + Secret) Call SSO with patient details (type=200). Use ?fields=vsee to include VSee ID and token in the response. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Patient's first name - last_name (required) — Patient's last name - type (required) — User type: 200 = Patient - email — Patient email address - code (required) — Unique patient identifier on your end (max 128 chars) ### Step 2: Create intake object POST /intakes (auth: User Token) Create an intake data object to capture the reason for visit. Uses the patient's access token from Step 1. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - type (required) — Intake type (1 = standard) - room_code (required) — Room code for the waiting room - reason_for_visit — Reason for visit / chief complaint ### Step 3: Create a walk-in visit POST /visits/add_walkin (auth: User Token) Create a walk-in visit. The intake_id links the intake data from Step 2. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - provider_id (required) — VSee member ID of the provider handling this visit (auto-fills from stored Provider Member ID) - intake_id (required) — Intake ID from Step 2 - room_code (required) — Room code for the waiting room ### Step 4: Redirect to video call Redirect: https://{your_clinic}.vseepreview.com/auth?sso_token={sso_token}&next=/visits/start/{visit_id} Redirect the patient directly into the video call/chat page for their visit. ## Appointment Scheduling URL: https://developers.vsee.io/use-cases/appointment-scheduling Log patient in using SSO, look up the room's consultation, create an intake, find an available time slot, then schedule the appointment. ### Step 1: Obtain patient access token POST /users/sso (auth: API Key + Secret) Call SSO with patient details (type=200). Use ?fields=vsee to include VSee ID and token in the response. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Patient's first name - last_name (required) — Patient's last name - type (required) — User type: 200 = Patient - email — Patient email address - code (required) — Unique patient identifier on your end (max 128 chars) ### Step 2: Get room information GET /rooms/{room_code} (auth: Account Code Only) Look up room details. The response's data.payment.consultations[0].id is the consultation_id used when fetching available slots. headers: - X-AccountCode (required) — Account code pathParams: - room_code (required) — Waiting room code (e.g., sandbox) ### Step 3: Create intake object POST /intakes (auth: User Token) Create an intake data object to capture the reason for visit. Uses the patient's access token from Step 1. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - type (required) — Intake type (1 = standard) - room_code (required) — Room code for the waiting room - reason_for_visit — Reason for visit / chief complaint ### Step 4: Get available slots GET /availability (auth: User Token) Fetch available appointment slots for the provider. start/end are Unix timestamps. duration is in seconds (900 = 15 min). slot_start/slot_end from the first slot auto-fill into Step 5. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code queryParams: - member_id (required) — Provider's VSee member ID (auto-fills from stored Provider Member ID) - start (required) — Search window start (Unix timestamp — defaults to now) - end (required) — Search window end (Unix timestamp — defaults to now + 7 days) - duration (required) — Slot duration in seconds - consultation_id (required) — Consultation ID from Step 2 - intake_id (required) — Intake ID from Step 3 ### Step 5: Create a scheduled appointment POST /visits (auth: User Token) Create the scheduled visit. type=2 marks it as scheduled. one_time_link_token is only returned if the clinic is configured for one-time appointment links. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - member_id (required) — Provider's VSee member ID (same as Step 4 — auto-fills from stored Provider Member ID) - intake_id (required) — Intake ID from Step 3 - room_code (required) — Room code - slot_start (required) — Start time from Step 4 (Unix timestamp) - slot_end (required) — End time from Step 4 (Unix timestamp) - type (required) — Visit type: 2 = scheduled ### Step 6: Build appointment link Redirect: https://{your_clinic}.vseepreview.com/members/appointment/{visit_id}?token={one_time_link_token} Uses the visit's one-time link token (not SSO token) for direct appointment access. ## eConsult (Async Visit) URL: https://developers.vsee.io/use-cases/econsult Log patient in using SSO, create an intake, then create an asynchronous e-consult. Providers assigned to the room will see it and can accept it. ### Step 1: Obtain patient access token POST /users/sso (auth: API Key + Secret) Call SSO with patient details (type=200). Use ?fields=vsee to include VSee ID and token in the response. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Patient's first name - last_name (required) — Patient's last name - type (required) — User type: 200 = Patient - email — Patient email address - code (required) — Unique patient identifier on your end (max 128 chars) ### Step 2: Create intake object POST /intakes (auth: User Token) Create an intake data object to capture the reason for visit. Uses the patient's access token from Step 1. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - type (required) — Intake type (1 = standard) - room_code (required) — Room code for the waiting room - reason_for_visit — Reason for visit / chief complaint ### Step 3: Create an e-consult POST /visits/add_econsult (auth: User Token) Create an asynchronous e-consult. Only intake_id and room_code are needed. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - intake_id (required) — Intake ID from Step 2 - room_code (required) — Room code — all providers in this room will see the e-consult ### Step 4: View via Patient Dashboard The e-consult can be viewed by the patient through the Patient Dashboard. Follow the "Patient Dashboard" use case to redirect the patient to their dashboard where they can track the e-consult status. ## Guest Invite URL: https://developers.vsee.io/use-cases/guest-invite Create a guest invite link to a video call. The patient SSOs in, creates an intake and walk-in visit, then uses the visit code to generate a shareable invite link. ### Step 1: Obtain patient access token POST /users/sso (auth: API Key + Secret) Call SSO with patient details (type=200). Use ?fields=vsee to include VSee ID and token in the response. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Patient's first name - last_name (required) — Patient's last name - type (required) — User type: 200 = Patient - email — Patient email address - code (required) — Unique patient identifier on your end (max 128 chars) ### Step 2: Create intake object POST /intakes (auth: User Token) Create an intake data object to capture the reason for visit. Uses the patient's access token from Step 1. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - type (required) — Intake type (1 = standard) - room_code (required) — Room code for the waiting room - reason_for_visit — Reason for visit / chief complaint ### Step 3: Create a walk-in visit POST /visits/add_walkin (auth: User Token) Create a walk-in visit. The response includes data.code — a unique visit code used for the invite link. headers: - X-ApiToken (required) — User access token from SSO response - X-AccountCode (required) — Account code bodyFields: - provider_id (required) — VSee member ID of the provider handling this visit (auto-fills from stored Provider Member ID) - intake_id (required) — Intake ID from Step 2 - room_code (required) — Room code ### Step 4: Build guest invite link Redirect: https://{your_clinic}.vseepreview.com/visits/join/{visit_code} Use data.code from the visit response (not data.id) to build the invite link. No authentication is required to join via this link. ## Provider Dashboard URL: https://developers.vsee.io/use-cases/provider-dashboard Log a provider into VSee Clinic's provider dashboard for telehealth functionality — manage queue, accept visits, start video calls, view patient records. ### Step 1: Obtain provider access token POST /users/sso (auth: API Key + Secret) Call SSO with provider details (type=400). Use ?fields=vsee to include VSee ID and token. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Provider's first name - last_name (required) — Provider's last name - type (required) — User type: 400 = Provider - email — Provider email address - code (required) — Unique provider identifier on your end - subtype — Provider subtype (e.g., 482 = Doctor, 470 = CSR) ### Step 2: Redirect to provider dashboard Redirect: https://{your_clinic}.vseepreview.com/auth?sso_token={sso_token}&next=/providers/dashboard Redirect the provider to their dashboard. ## Provider with Room URL: https://developers.vsee.io/use-cases/provider-dedicated-room Set up multiple providers with their own dedicated waiting rooms. Each provider gets their own room to accept their own pool of patients. ### Step 1: Obtain provider access token POST /users/sso (auth: API Key + Secret) SSO the provider (type=400). Response includes data.id (user ID) for room assignment and data.token.token for redirect. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Provider's first name - last_name (required) — Provider's last name - type (required) — User type: 400 = Provider - email — Provider email address - code (required) — Unique provider identifier on your end - subtype — Provider subtype (e.g., 482 = Doctor, 470 = CSR) ### Step 2: Create a waiting room POST /rooms (auth: Admin Token) Create a dedicated room. Sends X-ApiKey, X-ApiSecret, and the Clinic Admin API Token together. Slug must be unique. headers: - X-AccountCode (required) — Account code - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-ApiToken (required) — Clinic Admin API Token from dashboard bodyFields: - domain (required) — Clinic domain (auto-fills from stored Clinic URL) - slug (required) — Unique room slug/identifier — developer-defined per room - name (required) — Room display name — developer-defined per room ### Step 3: Assign provider to the room POST /users/{id}/rooms (auth: Admin Token) Link the room to the provider. Replace {id} with data.id from Step 1. Uses Admin Token. headers: - X-ApiToken (required) — Clinic Admin API Token from dashboard - X-AccountCode (required) — Account code pathParams: - id (required) — Provider's user ID from Step 1 bodyFields: - code (required) — Room code from Step 2 ### Step 4: Redirect to provider dashboard Redirect: https://{your_clinic}.vseepreview.com/auth?sso_token={sso_token}&next=/providers/dashboard Redirect the provider to their dashboard where they'll see their dedicated room. ## Member SSO URL: https://developers.vsee.io/use-cases/mobile-sso Get an SSO token and inject it into your mobile app. Your backend calls SSO, receives the token, and passes it to the mobile app to open a WebView. ### Step 1: Obtain patient access token POST /users/sso (auth: API Key + Secret) Your backend calls SSO with ?fields=vsee. Response includes the SSO token and VSee credentials. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields — Set to 'vsee' to include VSee ID and token bodyFields: - first_name (required) — Patient's first name - last_name (required) — Patient's last name - type (required) — User type: 200 = Patient - email — Patient email address - code (required) — Unique patient identifier on your end (max 128 chars) ### Step 2: Pass token to mobile app Send the SSO token (data.token.token) from the response to your mobile app via your existing auth flow or internal API. ### Step 3: Open WebView with token Redirect: https://{your_clinic}.vseepreview.com/auth?sso_token={sso_token}&next=/u/{room_slug} In the mobile app, open a WebView pointing to the auth URL. ## Browser Call SDK URL: https://developers.vsee.io/use-cases/browser-call-sdk Use the VSee Browser Call SDK to embed video calling directly into your app. Control the call UI entirely using the VSee ID and token from the SSO response. ### Step 1: SSO with vsee fields POST /users/sso (auth: API Key + Secret) Call SSO with ?fields=vsee to get data.vseeid and data.vsee_token for the Browser Call SDK. headers: - X-ApiKey (required) — API Key - X-ApiSecret (required) — API Secret - X-AccountCode (required) — Account code queryParams: - fields (required) — Must be 'vsee' to get SDK credentials bodyFields: - first_name (required) — Patient's first name - last_name (required) — Patient's last name - type (required) — User type: 200 = Patient - email — Patient email address - code (required) — Unique patient identifier on your end (max 128 chars) ### Step 2: Initialize the SDK Use data.vseeid and data.vsee_token from Step 1 to initialize the Browser Call SDK. This gives you full control over the video call UI. ### Step 3: Start or join a call Use the SDK methods to start a new call or join an existing room. Refer to the Browser Call SDK documentation for the full API reference. # API reference ## 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." } ``` ## VSee Clinic Visit API Landing: https://developers.vsee.io/api/visit-api · Spec JSON: https://developers.vsee.io/specs/visit_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 The VSee Clinic Visit API allows developers to manage intakes, walk-in visits, e-consults, and appointments within the VSee Clinic platform. ### Visit Status Codes | Code | Meaning | Description | |------|---------|-------------| | 10 | Pending | Visit was just created | | 20 | Confirmed | Appointment is confirmed | | 25 | In-progress | Visit is in progress | | 30 | Completed | Visit is closed | | 40 | Deleted / Cancelled | Visit is cancelled by patient or provider | ### Visit Subtypes | Code | Meaning | Description | |------|---------|-------------| | 1 | In-person | In-person visit, no video call | | 2 | Phone | Appointment by phone, no video call | | 3 | Video | Default: VSee video call | | 4 | E-consult | Async visit, no video call | ### POST /intakes URL: https://developers.vsee.io/api/visit-api/post/intakes operationId: createIntake Auth: User Token — Requires a user access token from login or SSO. Create intake data object Create a new intake object. Supports custom JSON field-value pairs. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - provider_id (query, integer, optional) — The ID of the provider who is being visited (optional) - reason_for_visit (query, string, optional) — Reason for visit (optional) - type (query, integer, optional) — Visit type: 1=walkin, 2=schedule (optional) - member_id (query, string, optional) — Patient's code ID (optional) - room_code (query, string, required) — Room's code - location (query, string, optional) — State location code like CA, AL (optional) - phone (query, string, optional) — Patient phone number (optional) Request body (application/x-www-form-urlencoded): Example request: ```json null ``` Responses: - 200 — Intake created successfully ```json { "data": { "id": "56e8c536-566c-44b6-bbca-66f0ac1f0144" } } ``` - 400 — Bad request - missing required parameters ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` - 401 — Unauthorized - invalid or missing API token ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### POST /intakes/{id} URL: https://developers.vsee.io/api/visit-api/post/intakes/%7Bid%7D operationId: updateIntake Auth: User Token — Requires a user access token from login or SSO. Update intake data object Update an existing intake object Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Intake ID - provider_id (query, integer, optional) — The ID of the provider (optional) - reason_for_visit (query, string, optional) — Reason for visit (optional) - location (query, string, optional) — State location code (optional) - phone (query, string, optional) — Patient phone number (optional) Responses: - 200 — Intake updated successfully ```json { "data": { "id": "56e8c536-566c-44b6-bbca-66f0ac1f0144" } } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### GET /intakes/{id} URL: https://developers.vsee.io/api/visit-api/get/intakes/%7Bid%7D operationId: getIntake Auth: User Token — Requires a user access token from login or SSO. Get intake data object Retrieve a selected intake data object Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Intake ID Responses: - 200 — Intake retrieved successfully ```json { "data": { "modified": 1471465080, "created": 1471465080, "type": "1", "reason_for_visit": "the reason", "attachments": [ { "_id": "57b4c65d-7ef8-461f-8951-43b1ac1f0144", "name": "document.png", "path": "files/2016/08/17/57b4c65d-7ef8-461f-8951-43b1ac1f0144.png", "size": 12859, "ext": "png" } ], "id": "57b4c678-de20-4c1a-a52b-43e9ac1f0144" } } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### POST /visits/add_walkin URL: https://developers.vsee.io/api/visit-api/post/visits/add_walkin operationId: createWalkinVisit Auth: User Token — Requires a user access token from login or SSO. Create a walk-in visit Create a new walk-in visit for a patient Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - provider_id (query, string, optional) — The ID of the provider (optional) - intake_id (query, string, required) — The ID of the intake - visit_data_id (query, string, required) — The ID of a scheduled appointment - visit_id (query, string, optional) — The ID of a scheduled appointment (optional) - user_code (query, string, optional) — Patient's code ID (optional) - room_code (query, string, required) — Current room's code Responses: - 200 — Walk-in visit created successfully ```json { "data": { "id": "1525", "member_id": "508", "provider_id": "509", "account_code": null, "code": "56e8c580f55c44a2868b66f0ac1f0144", "start": "1458095488", "end": "1458096388", "type": "1", "status": "10", "room_id": null, "intake": { "provider": "509", "reason_for_visit": "Test intake functionalities 1", "type": "1", "visit_id": "1525", "id": "56e8c536-566c-44b6-bbca-66f0ac1f0144" }, "provider": { "id": "509", "first_name": "Ligeng", "last_name": "Doctor" }, "member": { "id": "508", "first_name": "Ligeng", "last_name": "01" } } } ``` - 400 — Bad request - missing required parameters ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### POST /visits/add_econsult URL: https://developers.vsee.io/api/visit-api/post/visits/add_econsult operationId: createEconsult Auth: User Token — Requires a user access token from login or SSO. Create an asynchronous e-consult visit Create an asynchronous e-consult. The e-consult will be created without scheduling, and providers will see it on their dashboards to accept. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Request body (application/json): - intake_id (string, required) — The ID of the intake - room_code (string, required) — Room code (required) Example request: ```json { "intake_id": "6050d1a8-b120-45b4-a568-61a664457b11", "room_code": "vclinic_room_code" } ``` Responses: - 200 — E-consult created successfully ```json { "data": { "incharge": false, "isEditExpired": false, "id": "14814100", "member_id": 14396847, "provider_id": 0, "account_code": "vclinic", "code": "6050d2e590d847429d312c8664457b11", "start": 1615909605, "end": 1615910505, "type": 3, "status": 20, "room_id": 10019500, "room_code": "vclinic_room_code", "member": { "id": "14396847", "code": "member_01", "first_name": "Ligeng", "last_name": "Member 01" }, "intake": { "reason_for_visit": "This is to test the API", "question_1": "Answer 1", "question_2": "Answer 2", "id": "6050d1a8-b120-45b4-a568-61a664457b11" }, "account": { "code": "vclinic", "name": "VClinic" } } } ``` - 400 — Bad request - missing required parameters ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### GET /availability URL: https://developers.vsee.io/api/visit-api/get/availability operationId: getAvailability Auth: User Token — Requires a user access token from login or SSO. Get provider's available slots Retrieve available appointment slots for providers based on search criteria Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - room_code (query, string, optional) — Room code (optional if using intake_id) - start (query, integer, required) — UNIX timestamp - search for available slots from this start time - end (query, integer, required) — UNIX timestamp - search for available slots up to this end time - duration (query, integer, optional) — Duration in seconds - search for available slots during this duration (optional) - provider_id (query, string, optional) — Provider ID - pick only this provider's slots (optional) - intake_id (query, string, optional) — Intake ID - should be passed when patient is choosing a slot (optional) - consultation_id (query, string, optional) — Consultation ID - helps determine slot duration (optional) - location (query, string, optional) — Location code like AL, CA (optional - for filtering by state) Responses: - 200 — Available slots retrieved successfully ```json { "data": { "slots": [ { "slot_id": "10996909", "slot_start": 1669239900, "slot_end": 1669240800, "slot_booked": 0, "slot_available": 1, "group_id": "637e920e-bd34-4d3f-82c0-804b0adc0a9f" }, { "slot_id": "10996909", "slot_start": 1669240800, "slot_end": 1669241700, "slot_booked": 0, "slot_available": 1, "group_id": "637e920e-bd34-4d3f-82c0-804b0adc0a9f" } ], "slot_data": { "10996909": { "id": "10996909", "provider_id": "12456470", "account_code": "carebyte", "start": "1669239900", "end": "1669243500", "group_id": "637e920e-bd34-4d3f-82c0-804b0adc0a9f", "status": "10", "consultation": { "duration": 15, "slots": 1 } } } } } ``` - 400 — Bad request - missing required parameters ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### POST /visits URL: https://developers.vsee.io/api/visit-api/post/visits operationId: createAppointment Auth: User Token — Requires a user access token from login or SSO. Create an appointment Create a new scheduled appointment for a patient with a provider Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - member_id (query, string, optional) — The ID of the visiting patient (optional) - slot_start (query, integer, required) — UNIX timestamp of appointment beginning - slot_end (query, integer, required) — UNIX timestamp of appointment ending - room_code (query, string, required) — Room code (required) - type (query, integer, required) — Visit type: 2=scheduling - intake_id (query, string, required) — The ID of the intake - provider_id (query, string, optional) — The ID of the provider (optional) Responses: - 200 — Appointment created successfully ```json { "data": { "member_id": 17778181, "provider_id": 12456470, "account_code": "vclinic", "code": "615f2e2eabc46ad94e9b6457b11", "start": 1631628616, "end": 1631628916, "type": 2, "status": 30, "room_code": "vclinicroom", "created": 1633627694, "modified": 1633630312, "provider": { "id": "12456470", "email": "doctor@vseelab.com", "full_name": "Dr. Anton Provider" }, "member": { "id": "17778181", "email": "patient@vseelab.com", "full_name": "Anton Test" }, "intake_id": "615f2de7-8ab8-48d3-80d8-53f564457b11" } } ``` - 400 — Bad request - missing required parameters ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### GET /visits URL: https://developers.vsee.io/api/visit-api/get/visits operationId: listVisits Auth: User Token — Requires a user access token from login or SSO. List visits Get the visits list of the patient. Upcoming appointments have start > current timestamp. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - room_code (query, string, optional) — Filter visits by room code - start_time (query, integer, optional) — Filter visits starting after this UNIX timestamp - end_time (query, integer, optional) — Filter visits ending before this UNIX timestamp - status (query, string, optional) — Filter by visit status. Values: 10 (Pending), 20 (Confirmed), 25 (In-progress), 30 (Completed), 40 (Cancelled) - fields (query, string, optional) — Comma-separated field names to return. Include `recordings` to receive recording objects for each visit. - with_recordings_only (query, integer, optional) — Set to `1` to filter out visits without recordings. When `fields` includes `recordings`, this flag includes the recordings object in each visit. [enum: 0, 1] Responses: - 200 — Visits list retrieved successfully ```json { "data": [ { "id": "7727", "member_id": "575", "provider_id": "1096", "account_code": "vclinic", "code": "57a07c26947c4544aeef4e5cac1f0144", "start": "1470669300", "end": "1470670200", "type": "2", "status": "20", "created": 1470135334, "modified": 1470135334, "provider": { "id": "1096", "first_name": "Anton", "last_name": "Provider III" }, "member": { "id": "575", "first_name": "Keven2", "last_name": "Teodoro2" } } ] } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### GET /visits/{id} URL: https://developers.vsee.io/api/visit-api/get/visits/%7Bid%7D operationId: getVisit Auth: User Token — Requires a user access token from login or SSO. Get visit detail Get detailed information for a specific visit or appointment Returns full visit details including members, intake data, meeting info, and (optionally) recordings. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Visit ID Responses: - 200 — Visit details retrieved successfully ```json { "data": { "id": "18407167", "member_id": 17778181, "provider_id": 12456470, "account_code": "vclinic", "code": "615f2e2eabc46ad94e9b6457b11", "start": 1631628616, "end": 1631628916, "actual_start": 1631628211, "type": 2, "status": 30, "room_code": "vclinicroom", "created": 1633627694, "modified": 1633630312, "provider": { "id": "12456470", "email": "doctor@vseelab.com", "full_name": "Dr. Anton Provider" }, "member": { "id": "17778181", "email": "patient@vseelab.com", "full_name": "Anton Test", "phone": "5551231122" }, "intake": { "provider_id": "12456470", "member_id": "17778181", "room_code": "vclinicroom", "reason_for_visit": "Follow-up consultation" } } } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### POST /visits/{id} URL: https://developers.vsee.io/api/visit-api/post/visits/%7Bid%7D operationId: updateVisit Auth: User Token — Requires a user access token from login or SSO. Update an appointment Update an existing appointment (e.g., change time or provider) Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Visit ID - version (query, integer, optional) — API version - use 2 for update operations - slot_start (query, integer, optional) — UNIX timestamp of new appointment start (optional) - slot_end (query, integer, optional) — UNIX timestamp of new appointment end (optional) - provider_id (query, string, optional) — New provider ID (optional). Set to 0 to remove provider. Responses: - 200 — Visit updated successfully ```json { "data": { "member_id": 567, "provider_id": 566, "account_code": "vclinic", "code": "615f2e2eabc46ad94e9b6457b11", "start": 1631628616, "end": 1631628916, "type": 2, "status": 30 } } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### POST /visits/close URL: https://developers.vsee.io/api/visit-api/post/visits/close operationId: closeVisit Auth: User Token — Requires a user access token from login or SSO. Close or cancel a visit Close, cancel, or end a visit or appointment Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (query, string, required) — The ID of the visit/appointment - reason (query, string, optional) — Reason for closing. Options: patient_end_call, patient_exit_room, call_ended, patient_cancel_appointment, max_waiting_time_reached Responses: - 200 — Visit closed successfully ```json { "data": { "id": "1525" } } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### POST /visits/delete URL: https://developers.vsee.io/api/visit-api/post/visits/delete operationId: deleteVisit Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App). Force cancel a visit Force cancel an existing visit. Requires admin token. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (query, string, required) — The ID of the visit/appointment Responses: - 200 — Visit deleted successfully ```json { "data": {} } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### GET /visits/current URL: https://developers.vsee.io/api/visit-api/get/visits/current operationId: getCurrentVisit Auth: User Token — Requires a user access token from login or SSO. Get current visit in progress Get the visit that is currently in progress for the authenticated user Parameters: - X-ApiToken (header, string, required) — API token Responses: - 200 — Current visit retrieved successfully ```json { "data": { "id": "1504", "member_id": "508", "provider_id": "509", "account_code": "fruitstreet", "code": "56e7b1d2b90c4d68953e3d02ac1f0144", "start": "1459973100", "end": "1459974000", "type": "2", "status": "40", "completed_by": "508", "created": 1458024914, "modified": 1458024914, "intake": { "provider": "509", "reason_for_visit": "Test intake functionalities", "type": "1", "id": "56e7b104-ded0-4096-979b-395bac1f0144" }, "provider": { "id": "509", "first_name": "Ligeng", "last_name": "Doctor" }, "member": { "id": "508", "first_name": "Ligeng", "last_name": "01" } } } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ### GET /visits/{id}/exports/visit_summary URL: https://developers.vsee.io/api/visit-api/get/visits/%7Bid%7D/exports/visit_summary operationId: exportVisitSummary Auth: User Token — Requires a user access token from login or SSO. Export visit summary Retrieve a PDF visit summary for a specific visit Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Visit ID Responses: - 200 — Visit summary exported successfully ```json { "data": { "url": "https://clinic.vsee.me/visits/exports/d6880792f1fa01xxxxx" } } ``` - 401 — Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or missing API token" } ``` ## Visit Messages API Landing: https://developers.vsee.io/api/visit-messages-api · Spec JSON: https://developers.vsee.io/specs/visit_messages_api_openapi.json Base URL: https://api.vseepreview.com Asynchronous messaging on an eConsult visit: patients send and read messages through the API while providers reply from the VSee Clinic dashboard. Every new message fires a `visit.message.created` webhook so an integrator's backend can notify its users without polling. Authorization is participant-scoped — a user can only read or write messages on visits they are part of (patient, assigned provider, or host). ## Webhooks This API emits one event. Its payload, delivery contract and handling steps are documented on its own page — see **`visit.message.created`** in the sidebar. | Event | Fires when | |-------|------------| | `visit.message.created` | Any new message is added to a visit thread, in either direction | ### GET /api/visits/{visit_id}/messages URL: https://developers.vsee.io/api/visit-messages-api/get/api/visits/%7Bvisit_id%7D/messages operationId: getVisitMessages Read the conversation Returns the visit's message thread. The list is append-only and chronological (oldest first by default). **Polling for new replies** — because the thread is append-only and chronological, request `?skip=`; the response contains only what's new, and `total_count` tells you when you're caught up. Polling is only needed as a fallback: subscribe to the `visit.message.created` webhook instead and fetch the thread when it fires. Parameters: - X-ApiToken (header, string, required) — API token — the same token returned by the SSO endpoint (`data.token.token`) - visit_id (path, string, required) — ID of the visit whose thread is being read - limit (query, integer, optional) — Page size. Default 25, maximum 200. [default: 25] - skip (query, integer, optional) — Offset into the list. Default 0. [default: 0] - page (query, integer, optional) — Alternative to `skip`: skip = (page − 1) × limit. - sort (query, string, optional) — Sort field. Use `sort=created&order=desc` (or the compact `sort=created:desc`) to return latest first. Default is oldest first. - order (query, string, optional) — Sort direction, used with `sort`. [enum: asc, desc] Responses: - 200 — Message thread retrieved successfully ```json { "data": [ { "id": "b505f15c-8b98-43ea-a8e8-e29188b5f757", "type": "patient_message", "actor": { "id": "1000004436", "type": 200, "display_name": "An VSee" }, "content": "Thank you doctor — what did you find?", "created": 1786745961.166 } ], "total_count": 7 } ``` - 400 — Missing token ```json { "code": 400, "message": "Missing token" } ``` - 401 — Invalid or expired token ```json { "code": 401, "message": "Invalid token" } ``` - 403 — The authenticated user is not a participant on this visit ```json { "code": 403, "message": "Not a participant on this visit" } ``` - 404 — Visit not found ```json { "code": 404, "message": "Visit not found" } ``` ### POST /api/visits/{visit_id}/messages URL: https://developers.vsee.io/api/visit-messages-api/post/api/visits/%7Bvisit_id%7D/messages operationId: createVisitMessage Send a patient message Posts a message to the visit thread as the authenticated user. The message appears in the provider's Visit Chat in real time. Attachments reuse the existing `POST /files` upload flow — pass the returned file ids in `attachment_ids`. A closed eConsult returns `409`: history stays readable, but a new concern should open a new eConsult. A successful post fires a `visit.message.created` webhook with `data.actor_type` set to the sender — see the webhook section on the API overview page. Parameters: - X-ApiToken (header, string, required) — API token — the same token returned by the SSO endpoint (`data.token.token`) - visit_id (path, string, required) — ID of the visit to post the message to Request body (application/json): - content (string, required) — Message text (UTF-8). Required, must be a non-empty string. - attachment_ids (array[string], optional) — Optional file ids from the `POST /files` upload flow Example request: ```json { "content": "Hi doctor, my molar still aches when I bite down.", "attachment_ids": [] } ``` Responses: - 201 — Message created successfully ```json { "data": { "id": "83c3b3d7-346c-4ac9-8276-f96ac8356e25", "type": "patient_message", "actor": { "id": "1000004436", "type": 200, "display_name": "An VSee" }, "content": "Hi doctor, my molar still aches when I bite down.", "created": 1786755119.482 } } ``` - 400 — Missing token, or `content` missing/empty ```json { "code": 400, "message": "content is required" } ``` - 401 — Invalid or expired token ```json { "code": 401, "message": "Invalid token" } ``` - 403 — The authenticated user is not a participant on this visit ```json { "code": 403, "message": "Not a participant on this visit" } ``` - 404 — Visit not found ```json { "code": 404, "message": "Visit not found" } ``` - 409 — Visit is closed for new messages (history remains readable) ```json { "code": 409, "message": "Visit is closed for new messages" } ``` ### WEBHOOK visit.message.created URL: https://developers.vsee.io/api/visit-messages-api/webhook/visit.message.created API: Visit Messages API — https://developers.vsee.io/api/visit-messages-api Direction: inbound — delivered to your configured webhook URL, not called by you. New message on the visit thread Fires for **every** new message on the visit, in either direction — patient messages sent through this API and provider replies sent from the VSee Clinic dashboard. Filter on `data.actor_type` if you only want one side. The payload is a thin pointer: it deliberately carries **no message content and no PHI**. Treat it as a signal to fetch, then read the thread with `GET /api/visits/{visit_id}/messages`. ## Delivery Configure the destination URL per clinic account in Admin settings. There is no signature header — restrict your endpoint by network or use an unguessable path. | Behaviour | Contract | |-----------|----------| | Acknowledgement | Return any `2xx` within 30 seconds | | Retries | Up to 5 attempts, roughly 60 seconds apart | | De-duplication | Retries repeat a delivery — de-duplicate on `data.message_id` | | Ordering | Not guaranteed; use `data.ts` to order | | Latency | Seconds for messages sent through this API, up to ~2 minutes for provider replies | ## Handling 1. Acknowledge immediately — do the work after responding, not before. 2. Skip the event if you have already seen its `data.message_id`. 3. Call `GET /api/visits/{visit_id}/messages?skip=` to pull only what is new. Payload (application/json): - id (string, required) — Unique id for this delivery. Changes on each retry — do not de-duplicate on it. - type (string, required) — Event name [one of: visit.message.created] - created (integer, required) — UNIX timestamp when the event was emitted - account_code (string, required) — Clinic account the visit belongs to - version (string, required) — Payload version - data (object, required) — Pointer to the new message. Carries no message content or PHI. - data.visit_id (string, required) — Visit whose message thread changed - data.message_id (string, required) — The new message. De-duplicate on this — retries repeat a delivery. - data.actor_type (string, required) — Who sent the message [one of: patient, provider] - data.ts (integer, required) — UNIX timestamp when the message was created Example delivery: ```json { "id": "6a47ea02-4809-4af6-b8f6-c56bc2bd2adb", "type": "visit.message.created", "created": 1786755119, "account_code": "aubrey", "version": "1.0", "data": { "visit_id": "1000021648", "message_id": "83c3b3d7-346c-4ac9-8276-f96ac8356e25", "actor_type": "provider", "ts": 1786755119 } } ``` ## VSee Clinic Rooms API Landing: https://developers.vsee.io/api/rooms-api · Spec JSON: https://developers.vsee.io/specs/rooms_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 The VSee Clinic Rooms API allows developers to manage video consultation rooms within the VSee Clinic platform. ## Room Codes Every room has a unique `code` (e.g., `my-room-123`). The room code is used to identify the room in API calls (e.g., `PUT /rooms/{code}`) and to construct the room URL for joining: `https://{account_code}.vsee.me/{room_code}`. When creating a room, you can optionally specify a `code`. If omitted, the system generates one automatically. Room codes must be unique within your clinic. ## Authentication Reading rooms (`GET /rooms`, `GET /rooms/{code}`) requires only the `X-AccountCode` header. Creating, updating, or deleting rooms requires the **Clinic Admin API Token** in the `X-ApiToken` header — not a user session token. ### GET /rooms URL: https://developers.vsee.io/api/rooms-api/get/rooms operationId: listRooms Auth: Account Code Only — Only requires the X-AccountCode header. No token needed. List rooms Retrieve a list of rooms with pagination. This is a public endpoint. **Note:** The Rooms API supports the DataTable API format for server-side pagination and filtering. Parameters: - X-AccountCode (header, string, required) — Account code - page (query, integer, optional) — Page number for pagination - limit (query, integer, optional) — Number of records per page Responses: - 200 — Successful response ```json { "data": [ { "slug": "room1", "name": "Room 1", "domain": "demo.vsee.me", "code": "room1_code", "created": 1427922788, "modified": 1427922788 }, { "slug": "room2", "name": "Room 2", "domain": "demo.vsee.me", "code": "room2_code", "created": 1427922800, "modified": 1427922800 } ] } ``` ### POST /rooms URL: https://developers.vsee.io/api/rooms-api/post/rooms operationId: createRoom Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App). Create room Create a new room for video consultations. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Request body (application/json): - domain (string, required) — Clinic's domain - code (string, optional) — Room code (optional, should be unique) - slug (string, optional) — Room slug (optional) - name (string, required) — Room's name Example request: ```json { "domain": "vclinic.vsee.me", "code": "b4vjj", "slug": "provider00102", "name": "provider00102 room" } ``` Responses: - 200 — Room created successfully ```json { "data": { "visits": { "walkin": { "enabled": true }, "appointment": { "enabled": false } }, "auth": { "guest": { "type": 600, "log_in": { "enabled": true } } }, "subtitle": "If this is an emergency, please call 911.", "slug": "provider00102", "name": "provider00102 room", "domain": "vclinic.vsee.me", "active": true, "users": "85741", "account_code": "clinic", "provider_ids": [ "85741" ], "public_access_room": true, "modified": 1605728974, "created": 1605728974, "payment": { "consultations": [ { "id": "5fb57ace-4808-4346-ad3c-3348925862c1", "description": "15-min Consultation", "duration": 15, "amount": 0, "group": false, "charge": false, "slots": 1 } ], "currency": "USD" }, "operation_settings": { "is_closed": false, "close_msg": "Service currently not available. Please check back later", "default_timezone": "America/Los_Angeles" }, "id": "171", "code": "b4vjj" } } ``` - 400 — Room already exists ```json { "code": 400, "message": "In domain 'vclinic.vsee.me' slug 'uat2' already exists." } ``` ### GET /rooms/{code} URL: https://developers.vsee.io/api/rooms-api/get/rooms/%7Bcode%7D operationId: getRoom Auth: Account Code Only — Only requires the X-AccountCode header. No token needed. Get room details Retrieve detailed information about a specific room. This is a public endpoint. Parameters: - X-AccountCode (header, string, required) — Account code - code (path, string, required) — Room code Responses: - 200 — Successful response ```json { "data": { "description": "", "specialties": [ { "code": "general_care", "name": "Default", "duration": 15 }, { "code": "primary_care", "name": "Primary Care", "duration": 15 }, { "code": "psychiatry", "name": "Psychiatry", "duration": 30 }, { "code": "dermatology", "name": "Dermatology", "duration": 15 } ], "modified": 1466796316, "created": 1446802721, "payment": { "paymentCurrency": "USD", "consultations": [ { "description": "15-min Consultation", "amount": 0, "duration": 15 }, { "description": "30 min", "amount": 20, "duration": 30 }, { "description": "45 min", "amount": 40, "duration": 45 } ] }, "slug": "room1", "name": "Room 1", "domain": "demo.vsee.me", "code": "room1", "account_code": "DEMO-ACCOUNT", "operation_settings": { "close_message": { "html": "" }, "close_msg": "", "closed_days": [ "saturday" ], "default_timezone": "America/Los_Angeles", "is_closed": false, "is_closed_now": false, "is_open_all_time": false, "is_scheduled_closed": false } } } ``` ### GET /rooms/{code}/providers URL: https://developers.vsee.io/api/rooms-api/get/rooms/%7Bcode%7D/providers operationId: listRoomProviders Auth: Account Code Only — Only requires the X-AccountCode header. No token needed. List room providers Retrieve a list of providers associated with a specific room. This is a public endpoint. Parameters: - X-AccountCode (header, string, required) — Account code - code (path, string, required) — Room code Responses: - 200 — Successful response ```json { "data": [ { "id": "401", "username": "provider-401", "code": "", "subtype": "482", "first_name": "Jarod", "last_name": "Sun 401", "vseeid": "evisitdev+user401", "photo": null, "title": "", "suffix": "", "status": false, "short_bio": false } ] } ``` ### GET /rooms/{code}/providers/{id} URL: https://developers.vsee.io/api/rooms-api/get/rooms/%7Bcode%7D/providers/%7Bid%7D operationId: getRoomProvider Auth: Account Code Only — Only requires the X-AccountCode header. No token needed. Get room provider detail Retrieve detailed information about a specific provider in a room. This is a public endpoint. Parameters: - X-AccountCode (header, string, required) — Account code - code (path, string, required) — Room code - id (path, string, required) — Provider ID Responses: - 200 — Successful response ```json { "data": { "id": "826", "code": "55de45a2ce384a24ad633301ac1f0144", "first_name": "John", "last_name": "Will", "username": "provider1", "vseeid": "conciergedev+user826", "email": "anton+provider1@vsee.com", "active": true, "title": "Dr.", "suffix": "M.D.", "tos": false, "phone": "334 2222211", "subtype": "482", "status": false, "educational_training": "edu and training...", "professional_interests": "interests...", "personal_interests": "some personal hobby", "short_bio": "..." } } ``` ### GET /rooms/{code}/queue URL: https://developers.vsee.io/api/rooms-api/get/rooms/%7Bcode%7D/queue operationId: getRoomQueue Auth: Account Code Only — Only requires the X-AccountCode header. No token needed. Get room queue info Retrieve queue information for a specific room. The waiting time is calculated as average_visit_time * before_me. This is a public endpoint. Parameters: - X-AccountCode (header, string, required) — Account code - code (path, string, required) — Room code Responses: - 200 — Successful response ```json { "data": { "length": 10, "capacity": 100, "average_visit_time": 3600, "before_me": 3 } } ``` ### POST /users/{id}/rooms URL: https://developers.vsee.io/api/rooms-api/post/users/%7Bid%7D/rooms operationId: associateRoomToUser Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App). Associate room to user Associate a room with a user. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID Request body (application/json): - code (string, required) — Room code - default (boolean, optional) — Set this room as default (optional) Example request: ```json { "code": "b4vjj", "default": false } ``` Responses: - 200 — Room associated successfully ```json { "data": [ { "_id": "171", "slug": "provider00102", "name": "provider00102 room", "domain": "clinic.vseepreview.com", "code": "b4vjj", "active": true, "users": "85741", "account_code": "clinic", "provider_ids": [ "85741" ], "public_access_room": true, "modified": { "sec": 1605728974, "usec": 177000 }, "created": { "sec": 1605728974, "usec": 177000 }, "payment": { "consultations": [ { "id": "5fb57ace-4808-4346-ad3c-3348925862c1", "description": "15-min Consultation", "duration": 15, "amount": 0, "group": false, "charge": false, "slots": 1 } ] }, "default": false } ] } ``` ### DELETE /users/{id}/rooms/{room_code} URL: https://developers.vsee.io/api/rooms-api/delete/users/%7Bid%7D/rooms/%7Broom_code%7D operationId: removeRoomFromUser Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App). Remove room from user Remove a room association from a user. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID - room_code (path, string, required) — Room code Responses: - 200 — Room removed successfully ```json {} ``` ## Settings API Landing: https://developers.vsee.io/api/settings-api · Spec JSON: https://developers.vsee.io/specs/settings_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 ### GET /settings URL: https://developers.vsee.io/api/settings-api/get/settings Auth: User Token — Requires a user access token from login or SSO. Get all settings Retrieve all settings available for the account. Public access endpoint. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — Successful response ```json { "data": { "visit": { "time": { "max_wait_time": 86400 } } } } ``` ### GET /settings/{setting_key} URL: https://developers.vsee.io/api/settings-api/get/settings/%7Bsetting_key%7D Auth: User Token — Requires a user access token from login or SSO. Get specific setting Retrieve a specific settings value by key. Public access endpoint. For nested settings, use the full path with forward slashes (e.g. `visit/time/max_wait_time`). Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - setting_key (path, string, required) — The settings key or path (e.g. `visit/time/max_wait_time`) Responses: - 200 — Successful response ```json { "data": 86400 } ``` ## EMR API Landing: https://developers.vsee.io/api/emr-api · Spec JSON: https://developers.vsee.io/specs/emr_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 ### GET /users/{id}/emr URL: https://developers.vsee.io/api/emr-api/get/users/%7Bid%7D/emr Auth: User Token — Requires a user access token from login or SSO. Get user EMR data Retrieve all EMR (Electronic Medical Record) data for a user **Tip:** The `:id` parameter accepts dash (`-`) for the current user. Returns all EMR categories: allergies, conditions, surgeries, family_conditions, social_history, health_habits, medications. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID or dash (`-`) for current user Responses: - 200 — Successful response ```json { "data": { "allergies": { "data": [ { "substance": "A+D" } ], "modified": 1467667527, "modified_by": { "id": "575", "type": "200", "first_name": "Keven2", "last_name": "Teodoro2", "title": "Dr.", "Suffix": "MD" } }, "conditions": { "data": [ { "condition": "Bleeding problem" } ], "modified": 1465941203, "modified_by": {} } } } ``` ### POST /users/{id}/emr/{name} URL: https://developers.vsee.io/api/emr-api/post/users/%7Bid%7D/emr/%7Bname%7D Auth: User Token — Requires a user access token from login or SSO. Update EMR section Update a specific EMR section for a user Input fields should follow the schema from `GET /emr/schema` for the corresponding `:name` schema. ### EMR Data Formats Each POST body must include `data` (the health data) and optionally `data_not_reported` (boolean: true if user selects not to declare any data). **Conditions:** `{"data":[{"condition":"Asthma"},{"condition":"Bleeding problem"}], "data_not_reported":false}` **Surgeries:** `{"data":[{"procedure":"Heart valve replaced"}], "data_not_reported":false}` **Family History:** `{"data":[{"condition":"Alcoholism","relations":["Mother","Father"]}], "data_not_reported":false}` **Social History:** `{"data":{"marital_status":"Single","highest_ed":"Grammar school","occupation":"test","num_kids":"5"}, "data_not_reported":false}` **Health Habits:** `{"data":{"smoking":"Never","alcohol":"Never","drugs":"none","exercise":"Never"}, "data_not_reported":false}` **Medications:** `{"data":[{"name": "Tylenol"}], "data_not_reported":false}` **Allergies:** `{"data":[{"substance": "1-Day"}, {"substance": "12 Hour Nasal"}], "data_not_reported":false}` Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID or '-' for current user - name (path, string, required) — Name of EMR schema (conditions, surgeries, allergies, medications, family_conditions, social_history, health_habits) [enum: conditions, surgeries, allergies, medications, family_conditions, social_history, health_habits] Request body (application/json): - data (array, required) - data_not_reported (boolean, required) Example request: ```json { "data": [ { "condition": "Asthma" }, { "condition": "Bleeding problem" } ], "data_not_reported": false } ``` Responses: - 200 — Successful update ```json { "data": { "data": { "marital_status": "Single", "highest_ed": "Grammar school", "occupation": "test", "num_kids": "5" } } } ``` ## Pharmacy API Landing: https://developers.vsee.io/api/pharmacy-api · Spec JSON: https://developers.vsee.io/specs/pharmacy_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 ### GET /users/{id}/erx/prescriptions URL: https://developers.vsee.io/api/pharmacy-api/get/users/%7Bid%7D/erx/prescriptions Auth: User Token — Requires a user access token from login or SSO. Get user prescriptions Get list of current prescriptions for a patient **Tip:** The `:id` parameter accepts dash (`-`) for the current user. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID or dash (-) for current user - status (query, string, optional) — Status of prescriptions. Send `Current` by default. Responses: - 200 — Successful response ```json { "data": [ { "ID": "101544", "DrugID": "69202", "NDC": "59390003613", "Drug": "12 Hour Nasal 0.05% nasal spray", "Directions": "1 Milliliter(s) 1 to 2 times a day", "Qty": 5, "Status": "Current", "PrescriberName": "Dr. Rocky Charlette, N.P." } ] } ``` ### GET /users/{id}/erx/pharmacies URL: https://developers.vsee.io/api/pharmacy-api/get/users/%7Bid%7D/erx/pharmacies Auth: User Token — Requires a user access token from login or SSO. Get user pharmacies Get user's saved pharmacies **Tip:** The `:id` parameter accepts dash (`-`) for the current user. Returns an array of Pharmacy objects with location, contact info, and distance. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID or dash (-) for current user Responses: - 200 — Successful response ```json { "data": [ { "is_default": true, "name": "4700 Sunset Blvd", "address": "4700 Sunset Boulevard", "code": "0561539", "city": "Los Angeles", "state": "CA", "zip": "90027", "phone": "8663528725", "lat": 36.800488, "long": -116.71875, "distance": 0.95993211712521 } ] } ``` ### POST /users/{id}/erx/pharmacies URL: https://developers.vsee.io/api/pharmacy-api/post/users/%7Bid%7D/erx/pharmacies Auth: User Token — Requires a user access token from login or SSO. Save pharmacy Save patient's currently chosen pharmacy Save the patient's currently chosen pharmacy. **Note:** Set `type` to `mdtoolbox` when saving pharmacy data from MDToolbox search results. Include the `extra` object with the unmodified data returned by the pharmacy search API (contains NCPDPID, StoreName, etc.). Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID or dash (-) for current user Request body (application/json): - name (string, required) - code (string, required) - address (string, optional) - address_more (string, optional) - city (string, optional) - country (string, optional) - state (string, optional) - zip (string, optional) - phone (string, optional) - fax (string, optional) - lat (number, optional) - long (number, optional) - distance (number, optional) - type (string, optional) - extra (object, optional) Example request: ```json { "name": "A247PC00-Anesthesia 24/7, PC", "address": "1200 Freas Avenue", "code": "1001103", "city": "Berwick", "state": "PA", "zip": "18063", "phone": "5707525572", "fax": "6153972423", "type": "mdtoolbox", "extra": { "NCPDPID": "1001103", "StoreName": "A247PC00-Anesthesia 24/7, PC" } } ``` Responses: - 200 — Successful save ```json { "data": true } ``` ### DELETE /users/{id}/erx/pharmacies/{code} URL: https://developers.vsee.io/api/pharmacy-api/delete/users/%7Bid%7D/erx/pharmacies/%7Bcode%7D Auth: User Token — Requires a user access token from login or SSO. Delete pharmacy Delete the specified pharmacy from the user profile Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — User ID or dash (-) for current user - code (path, string, required) — Pharmacy code Responses: - 200 — Successful deletion ```json { "data": true } ``` ## Payment API Landing: https://developers.vsee.io/api/payment-api · Spec JSON: https://developers.vsee.io/specs/payment_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 Payment is integrated with Stripe. Use `GET /billing/settings` to retrieve the Stripe publishable key, then use Stripe.js client-side to tokenize card details before sending to VSee. Payment sources are scoped by `room_code` and optionally `provider_id`. ### GET /billing/settings URL: https://developers.vsee.io/api/payment-api/get/billing/settings Auth: User Token — Requires a user access token from login or SSO. Get payment settings Retrieve payment settings for the account Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — Successful response ```json { "data": { "stripe": { "publishable_key": "2342342" } } } ``` ### GET /billing/sources URL: https://developers.vsee.io/api/payment-api/get/billing/sources Auth: User Token — Requires a user access token from login or SSO. List payment sources Retrieve all payment sources from user account Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - type (query, string, optional) — Payment type (e.g. 'card') - room_code (query, string, required) — Room code to scope the payment source - provider_id (query, string, optional) — Provider ID (optional) to scope the payment source Responses: - 200 — Successful response ```json { "data": [ { "id": "card_19DrgXBY2jn2BCqQNpjjzuay", "type": "card", "brand": "Visa", "last4": "4242", "exp_month": 8, "exp_year": 2017, "is_default": true }, { "id": "card_19DrgXBY2jn2BCqQNpjjzub", "type": "card", "brand": "Visa", "last4": "4242", "exp_month": 8, "exp_year": 2017, "is_default": false } ] } ``` ### POST /billing/sources URL: https://developers.vsee.io/api/payment-api/post/billing/sources Auth: User Token — Requires a user access token from login or SSO. Add payment source Add a new payment source to user account Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - room_code (query, string, required) — Room code to scope the payment source - provider_id (query, string, optional) — Provider ID (optional) to scope the payment source Request body (application/json): - type (string, required) — Payment type (e.g. 'card') - token (string, required) — Token from Stripe Example request: ```json { "type": "string", "token": "string" } ``` Responses: - 200 — Successful creation ```json { "data": { "id": "card_19DrgXBY2jn2BCqQNpjjzuay", "type": "card", "brand": "Visa", "exp_month": 8, "exp_year": 2017, "last4": "4242", "is_default": true } } ``` ### GET /billing/sources/{id} URL: https://developers.vsee.io/api/payment-api/get/billing/sources/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Get payment source Retrieve a specific payment source Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Payment source ID - room_code (query, string, optional) — Room code to scope the payment source - provider_id (query, string, optional) — Provider ID (optional) to scope the payment source Responses: - 200 — Successful response ```json { "data": { "id": "card_19DrgXBY2jn2BCqQNpjjzuay", "type": "card", "brand": "Visa", "exp_month": 8, "exp_year": 2017, "last4": "4242", "is_default": true } } ``` ### PUT /billing/sources/{id} URL: https://developers.vsee.io/api/payment-api/put/billing/sources/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Set default payment source Set a payment source as default Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Payment source ID Request body (application/json): - is_default (boolean, optional) - room_code (string, optional) - provider_id (string, optional) Example request: ```json { "is_default": true, "room_code": "string", "provider_id": "string" } ``` Responses: - 200 — Successful update ```json { "data": { "id": "card_19DrgXBY2jn2BCqQNpjjzuay", "type": "card", "brand": "Visa", "exp_month": 8, "exp_year": 2017, "last4": "4242", "is_default": true } } ``` ### DELETE /billing/sources/{id} URL: https://developers.vsee.io/api/payment-api/delete/billing/sources/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Delete payment source Delete a payment source from user account Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Payment source ID Responses: - 200 — Successful deletion ```json { "data": [] } ``` ### POST /billing/invoices/process URL: https://developers.vsee.io/api/payment-api/post/billing/invoices/process Auth: User Token — Requires a user access token from login or SSO. Process invoice Process an invoice with optional coupon code Process an invoice, optionally applying a promo/coupon code. **Parameters:** - `promo_code` — Coupon code - `intake_id` — Required — intake ID to apply the coupon to - `create_invoice` — Set to `1` to create the invoice Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Request body (application/json): - promo_code (string, optional) - intake_id (string, required) - create_invoice (integer, optional) Example request: ```json { "promo_code": "string", "intake_id": "string", "create_invoice": 0 } ``` Responses: - 200 — Successful processing ```json { "data": { "currency": "USD", "consultation": { "description": "30 mins", "amount": 30, "duration": 30, "id": "58244a53-0f28-4ff9-bdbc-7468ac1f0144" }, "coupon": { "id": "10_percents_1479363579", "percent_off": 10, "valid": true }, "amount_due": 27 } } ``` ## Insurance API Landing: https://developers.vsee.io/api/insurance-api · Spec JSON: https://developers.vsee.io/specs/insurance_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 The insurance CRUD APIs can be called using either a patient's token or a Clinic Admin token. Insurance cards are categorized as `primary` or `secondary`. The import endpoint accepts up to 2 insurance details (one primary, one secondary). If an insurance type already exists, it will be overwritten on import. ### GET /users/{user_id}/insurances URL: https://developers.vsee.io/api/insurance-api/get/users/%7Buser_id%7D/insurances operationId: listInsurances Auth: User Token — Requires a user access token from login or SSO. List insurance cards Retrieve a list of insurance cards associated with a user Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID Responses: - 200 — List of insurance cards ```json { "data": [ { "card_type": "primary", "insurer_code": "(sandbox) HUMANA", "subscriber_number": "11000022", "group_number": "GN00022", "responsible_party": "self", "guarantor_first_name": "VSee", "guarantor_middle_name": "Edward", "guarantor_last_name": "Patient 11000022", "guarantor_dob": "1986-01-01", "guarantor_gender": 1, "guarantor_address": "54 Rainbow St", "guarantor_address_2": "#12-22", "guarantor_city": "Sunnyvale", "guarantor_zip": "10001", "guarantor_state": "CA", "consent": true } ], "version": "2.0" } ``` ### POST /users/{user_id}/insurances/import URL: https://developers.vsee.io/api/insurance-api/post/users/%7Buser_id%7D/insurances/import operationId: importInsurances Auth: User Token — Requires a user access token from login or SSO. Import insurance cards Import one or more insurance cards for a user. Array can include up to 2 insurances (primary and secondary). If insurance type already exists, it will be overwritten. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID Request body (application/json): - insurances (array[InsuranceCard], required) Example request: ```json { "insurances": [ { "card_type": "primary", "insurer_code": "(sandbox) HUMANA", "subscriber_number": "11000022", "group_number": "GN00022", "responsible_party": "self", "guarantor_first_name": "VSee", "guarantor_last_name": "Patient 11000022", "guarantor_middle_name": "Edward", "guarantor_dob": "1986-01-01", "guarantor_gender": 1, "guarantor_address": "54 Rainbow St", "guarantor_address_2": "#12-22", "guarantor_city": "Sunnyvale", "guarantor_zip": "10001", "guarantor_state": "CA", "consent": true } ] } ``` Responses: - 200 — Insurances imported successfully ```json { "data": [ { "card_type": "primary", "insurer_code": "(sandbox) HUMANA", "subscriber_number": "11000022", "group_number": "GN00022", "responsible_party": "self", "guarantor_first_name": "VSee", "guarantor_middle_name": "Edward", "guarantor_last_name": "Patient 11000022", "guarantor_dob": "1986-01-01", "guarantor_gender": 1, "guarantor_address": "54 Rainbow St", "guarantor_address_2": "#12-22", "guarantor_city": "Sunnyvale", "guarantor_zip": "10001", "guarantor_state": "CA", "consent": true } ], "version": "2.0" } ``` ### POST /users/{user_id}/insurances/{card_type} URL: https://developers.vsee.io/api/insurance-api/post/users/%7Buser_id%7D/insurances/%7Bcard_type%7D operationId: updateInsurance Auth: User Token — Requires a user access token from login or SSO. Update insurance Update primary or secondary insurance details for a user Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID - card_type (path, string, required) — Insurance card type [enum: primary, secondary] Request body (application/json): - card_type (string, optional) [enum: primary, secondary] - insurer_code (string, optional) - subscriber_number (string, optional) - subscriber_num (string, optional) - group_number (string, optional) - responsible_party (string, optional) - guarantor_first_name (string, optional) - guarantor_middle_name (string, optional) - guarantor_last_name (string, optional) - guarantor_dob (string, optional) - guarantor_gender (integer, optional) - guarantor_address (string, optional) - guarantor_address_2 (string, optional) - guarantor_city (string, optional) - guarantor_zip (string, optional) - guarantor_state (string, optional) - consent (boolean, optional) Example request: ```json { "card_type": "primary", "insurer_code": "(sandbox) HUMANA", "subscriber_number": "11000022", "group_number": "GN00022", "responsible_party": "self", "guarantor_first_name": "VSee", "guarantor_last_name": "Patient 11000022", "guarantor_middle_name": "Edward", "guarantor_dob": "1986-01-01", "guarantor_gender": 1, "guarantor_address": "54 Rainbow St", "guarantor_address_2": "#12-22", "guarantor_city": "Sunnyvale", "guarantor_zip": "10001", "guarantor_state": "CA", "consent": true } ``` Responses: - 200 — Insurance updated successfully ```json { "data": { "card_type": "primary", "insurer_code": "(sandbox) HUMANA", "subscriber_number": "11000022", "group_number": "GN00022", "responsible_party": "self", "guarantor_first_name": "VSee", "guarantor_middle_name": "Edward", "guarantor_last_name": "Patient 11000022", "guarantor_dob": "1986-01-01", "guarantor_gender": 1, "guarantor_address": "54 Rainbow St", "guarantor_address_2": "#12-22", "guarantor_city": "Sunnyvale", "guarantor_zip": "10001", "guarantor_state": "CA", "consent": true }, "version": "2.0" } ``` ### GET /users/{user_id}/insurances/{card_type} URL: https://developers.vsee.io/api/insurance-api/get/users/%7Buser_id%7D/insurances/%7Bcard_type%7D operationId: getInsurance Auth: User Token — Requires a user access token from login or SSO. Get insurance Retrieve primary or secondary insurance details for a user Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID - card_type (path, string, required) — Insurance card type [enum: primary, secondary] Responses: - 200 — Insurance details ```json { "data": { "card_type": "primary", "insurer_code": "(sandbox) HUMANA", "subscriber_number": "11000022", "group_number": "GN00022", "responsible_party": "self", "guarantor_first_name": "VSee", "guarantor_middle_name": "Edward", "guarantor_last_name": "Patient 11000022", "guarantor_dob": "1986-01-01", "guarantor_gender": 1, "guarantor_address": "54 Rainbow St", "guarantor_address_2": "#12-22", "guarantor_city": "Sunnyvale", "guarantor_zip": "10001", "guarantor_state": "CA", "consent": true }, "version": "2.0" } ``` ### DELETE /users/{user_id}/insurances/{card_type} URL: https://developers.vsee.io/api/insurance-api/delete/users/%7Buser_id%7D/insurances/%7Bcard_type%7D operationId: deleteInsurance Auth: User Token — Requires a user access token from login or SSO. Delete insurance Delete primary or secondary insurance for a user Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID - card_type (path, string, required) — Insurance card type [enum: primary, secondary] Responses: - 204 — Insurance deleted successfully ### POST /users/{user_id}/insurances/primary/eligibility/check URL: https://developers.vsee.io/api/insurance-api/post/users/%7Buser_id%7D/insurances/primary/eligibility/check operationId: checkEligibility Auth: User Token — Requires a user access token from login or SSO. Check eligibility Check and return queue status and current eligibility status for primary insurance Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID Responses: - 200 — Eligibility check initiated ```json { "data": { "job_id": "6552fefa-e620-4caa-9990-26940a7d6499", "status": "pending" } } ``` - 429 — Too many requests ```json { "code": 429, "message": "Started at Tue, 14 Nov 2023 12:05:00 +0700" } ``` ### GET /users/{user_id}/insurances/primary/eligibility URL: https://developers.vsee.io/api/insurance-api/get/users/%7Buser_id%7D/insurances/primary/eligibility operationId: getEligibilityStatus Auth: User Token — Requires a user access token from login or SSO. Get eligibility status Return queue status and current eligibility status for primary insurance Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID Responses: - 200 — Eligibility status ```json { "data": { "job_id": "655300b4-2378-4ec7-98bf-34b50a7d6499", "status": "pending" } } ``` ### GET /reports/claims URL: https://developers.vsee.io/api/insurance-api/get/reports/claims operationId: listClaims Auth: User Token — Requires a user access token from login or SSO. List claims Return list of visits with claim-relevant data Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - from_date (query, string, optional) — Start date for claims report (YYYY-MM-DD format) - to_date (query, string, optional) — End date for claims report (YYYY-MM-DD format) Responses: - 200 — List of claims ```json { "data": [ null ] } ``` ### GET /insurances/list/carriers URL: https://developers.vsee.io/api/insurance-api/get/insurances/list/carriers operationId: listCarriers Auth: User Token — Requires a user access token from login or SSO. List carriers Retrieve list of insurance carriers Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — List of carriers ```json { "data": [ { "name": "A AND I BENEFIT PLAN ADMINISTRATORS", "code": "AAND", "advancedmd": { "address": { "zip": "", "city": "", "state": "", "address1": "", "address2": "", "areacode": "UND" }, "cpid": "3296", "code": "car7339" } } ] } ``` ### GET /insurances/list/insurers URL: https://developers.vsee.io/api/insurance-api/get/insurances/list/insurers operationId: listInsurers Auth: User Token — Requires a user access token from login or SSO. List insurers Retrieve list of insurers Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — List of insurers ```json { "data": [ { "id": "AAND", "text": "A AND I BENEFIT ADMINISTRATORS", "description": "A AND I BENEFIT ADMINISTRATORS" }, { "id": "AARP", "text": "AARP", "description": "AARP" } ] } ``` ### GET /insurances/list/billing_modifiers URL: https://developers.vsee.io/api/insurance-api/get/insurances/list/billing_modifiers operationId: listBillingModifiers Auth: User Token — Requires a user access token from login or SSO. List billing modifiers Retrieve list of billing modifiers Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — List of billing modifiers ```json { "data": [ { "id": "20", "text": "20", "description": "20" }, { "id": "F8", "text": "F8", "description": "F8" } ] } ``` ### GET /insurances/list/dxs URL: https://developers.vsee.io/api/insurance-api/get/insurances/list/dxs operationId: listDiagnoses Auth: User Token — Requires a user access token from login or SSO. List diagnoses Retrieve list of diagnosis codes Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — List of diagnoses ```json { "data": [ { "code": "I10", "description": "Essential (primary) hypertension", "advancedmd": { "code": "diag0010" } }, { "code": "E11.9", "description": "Type 2 diabetes mellitus without complications", "advancedmd": { "code": "diag0021" } } ] } ``` ### GET /insurances/list/procedures URL: https://developers.vsee.io/api/insurance-api/get/insurances/list/procedures operationId: listProcedures Auth: User Token — Requires a user access token from login or SSO. List procedures Retrieve list of procedures Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — List of procedures ```json { "data": [ { "id": "10001", "text": "INITIAL CONSULTATION - BASIC ASSESSMENT", "description": "Basic initial consultation to assess patient health status" }, { "id": "10002", "text": "FOLLOW-UP VISIT - CONDITION MONITORING", "description": "Routine follow-up to monitor ongoing health conditions" } ] } ``` ## Clinic Account API Landing: https://developers.vsee.io/api/clinic-account-api · Spec JSON: https://developers.vsee.io/specs/clinic_account_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 ### GET /accounts/{code} URL: https://developers.vsee.io/api/clinic-account-api/get/accounts/%7Bcode%7D Auth: No Auth — This endpoint requires no authentication headers. Get account details Get current member's Account data including intake forms, signup form, and workflow steps. Public access endpoint — no authentication required. ### Key Response Fields - `Account.code` is used for starting visits and identifying the clinic. - `states.signup` contains the signup form schema. - `intake_steps` and `post_intake_steps` define the intake wizard flow. ### Intake Wizard Flow 1. Patient goes through all steps defined in `intake_steps` and `post_intake_steps` arrays. 2. Create/update Intake object during `intake_steps`. 3. When all `intake_steps` are passed, create a visit. 4. Go through `post_intake_steps` where the patient may update intake, take surveys, pick pharmacy, etc. 5. Each step has a `code` field defining the type of content. Parameters: - code (path, string, required) — Account code or dash (-) for current account Responses: - 200 — Successful response ```json { "data": { "id": "56ced820-55bc-43ca-9b35-4599ac1f0144", "code": "vclinic", "domain": "demo.vsee.me", "name": "VClinic", "portal_title": "", "files": [ { "file_id": "56b29a3e-a72c-49e1-93f0-4c23ac1f0144", "code": "logo", "path": "https://api.vsee.me/api_v3/files/56b29a3e-a72c-49e1-93f0-4c23ac1f0144" } ], "waiting_room": { "subtitle": "If this is an emergency, please call 911 or go to your nearest emergency department.", "enter_text": "Enter Lounge", "need_schedule": true, "show_code": true, "average_visit_time": 3600, "capacity": 100, "default_room_code": "ceproom1" } } } ``` ## Push Notification API Landing: https://developers.vsee.io/api/push-notification-api · Spec JSON: https://developers.vsee.io/specs/push_notification_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 ### Endpoint Types | Value | Meaning | |-------|---------| | 10 | Email | | 30 | Apple Push Notification (APNS) | | 40 | Google Cloud Messaging (GCM/FCM) | This API is primarily for mobile app push notification registration. ### POST /endpoints URL: https://developers.vsee.io/api/push-notification-api/post/endpoints Auth: User Token — Requires a user access token from login or SSO. Register device endpoint Register a new device for push notifications Register a device for push notifications. **Parameters:** - `key` — Device token (for Apple) or registration ID (for Android) - `type` — 30 for Apple Push Notification, 40 for Google Cloud Messaging Parameters: - X-ApiToken (header, string, required) — API token Request body (application/x-www-form-urlencoded): - key (string, required) — Device token (Apple) or registration ID (Android) - type (integer, required) — Device type: 30=APNS (Apple), 40=GCM (Google) Example request: ```json { "key": "string", "type": 0 } ``` Responses: - 200 — Successful registration ```json { "data": { "id": "551c5f64-a6d8-425d-b89c-581fac1f0144", "key": "123456", "user_id": "201", "type": 30, "created": 1427922788, "modified": 1427922788 } } ``` ### GET /endpoints URL: https://developers.vsee.io/api/push-notification-api/get/endpoints Auth: User Token — Requires a user access token from login or SSO. List endpoints Retrieve all notification endpoints for current user Parameters: - X-ApiToken (header, string, required) — API token - type (query, integer, optional) — Device type: 30=APNS, 40=GCM. Empty for all types. Responses: - 200 — Successful response ```json { "data": [ { "id": "551c5f64-a6d8-425d-b89c-581fac1f0144", "key": "123456", "user_id": "201", "type": 30, "arn": "arn:aws:sns:us-west-2:048881245029:endpoint/APNS/com.vsee.isos.TeleAssistance/203fd06c-e559-3fba-a47f-87844eca4e6e", "created": 1427922788, "modified": 1427922788 }, { "id": "551c6005-83d0-48f0-abfe-59c4ac1f0144", "key": "an@vsee.com", "user_id": "201", "type": 10, "created": 1427922949, "modified": 1427922949 } ] } ``` ### GET /endpoints/{id} URL: https://developers.vsee.io/api/push-notification-api/get/endpoints/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Get endpoint Retrieve a specific notification endpoint Parameters: - X-ApiToken (header, string, required) — API token - id (path, string, required) — Endpoint ID Responses: - 200 — Successful response ```json { "data": { "id": "551c5f64-a6d8-425d-b89c-581fac1f0144", "key": "123456", "user_id": "201", "type": 30, "created": 1427922788, "modified": 1427922788 } } ``` ### DELETE /endpoints/{id} URL: https://developers.vsee.io/api/push-notification-api/delete/endpoints/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Delete endpoint Delete a notification endpoint Parameters: - X-ApiToken (header, string, required) — API token - id (path, string, required) — Endpoint ID Responses: - 200 — Successful deletion ```json { "data": { "id": "551c5f64-a6d8-425d-b89c-581fac1f0144" } } ``` ### GET /notifications URL: https://developers.vsee.io/api/push-notification-api/get/notifications Auth: User Token — Requires a user access token from login or SSO. List notifications Retrieve notifications for current user Parameters: - X-ApiToken (header, string, required) — API token - size (query, integer, optional) — Fetch size — how many records to return. Default: 10. - last (query, integer, optional) — Unix timestamp in milliseconds. Only fetch notifications before this time. Use the `mtime` field from previous responses for pagination. Responses: - 200 — Successful response ```json { "data": [ { "id": "570f3f04-f1f4-4805-946e-178d50e631f8", "user_id": "201", "type": "foodlog.comment", "time": "1460616964", "mtime": 14606169641000, "is_new": false, "read": false, "title": "Johnathon Lavon commented on a photo", "image": "http://api.vsee.me/files/index/food/photo/1/250x250?auth_code=EXAMPLE_AUTH_CODE" } ] } ``` ### PUT /notifications/{id} URL: https://developers.vsee.io/api/push-notification-api/put/notifications/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Mark notification as read Mark a notification as read Parameters: - X-ApiToken (header, string, required) — API token - id (path, string, required) — Notification ID Responses: - 200 — Successful update ```json { "data": { "id": "570f3f04-f1f4-4805-946e-178d50e631f8", "user_id": "201", "type": "foodlog.comment", "time": 1460616964, "mtime": 14606169641000, "is_new": false, "read": true, "title": "Johnathon Lavon commented on a photo" } } ``` ### GET /notifications/badge URL: https://developers.vsee.io/api/push-notification-api/get/notifications/badge Auth: User Token — Requires a user access token from login or SSO. Get badge count Get the badge number for notifications Parameters: - X-ApiToken (header, string, required) — API token Responses: - 200 — Successful response ```json { "data": 5 } ``` ### POST /notifications/badge URL: https://developers.vsee.io/api/push-notification-api/post/notifications/badge Auth: User Token — Requires a user access token from login or SSO. Reset badge count Reset the badge number for notifications Parameters: - X-ApiToken (header, string, required) — API token Responses: - 200 — Successful reset ```json { "data": true } ``` ## File Upload API Landing: https://developers.vsee.io/api/file-upload-api · Spec JSON: https://developers.vsee.io/specs/file_upload_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 ### POST /files URL: https://developers.vsee.io/api/file-upload-api/post/files Auth: User Token — Requires a user access token from login or SSO. Upload file Upload a file with optional metadata ### File Categories (`meta.category`) - `intake_attachment` — Per-visit files, only visible on the visit page. - `user_consent` — User consent documents. - `user_avatar` — User profile picture. - `user_document` — Per-user profile documents, visible under the patient's Documents page and provider's Documents tab. ### Uploading on Behalf of a Patient When using a clinic/admin token to upload for a patient, include: - `meta.target.id` — The patient's user ID - `meta.target.type` — Set to `user` **Example (upload for patient):** ``` curl -X POST https://api.vseepreview.com/api_v3/files \ -H 'X-ApiToken: {admin_token}' \ -H 'X-AccountCode: {account_code}' \ -F file=@/path/to/file.png \ -F meta.target.id=20002340748 \ -F meta.target.type=user \ -F meta.category=user_document ``` Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Request body (multipart/form-data): - file (string, required) — Binary file content - meta.title (string, optional) — File title - meta.description (string, optional) — File description - meta.target.id (string, optional) — Target ID (user ID or visit ID). Required if uploading for someone else - meta.target.type (string, optional) — Target type (user or visit). Required if uploading for someone else - meta.category (string, optional) — File category (intake_attachment, user_consent, user_avatar, user_document) Example request: ```json { "file": "binary", "meta.title": "string", "meta.description": "string", "meta.target.id": "string", "meta.target.type": "string", "meta.category": "string" } ``` Responses: - 200 — Successful upload ```json { "data": { "id": "5e15d150-19b4-4cbd-b217-332fc71b6977", "name": "p878984.jpg", "size": 40679, "ext": "jpg", "fullpath": "https://vclinic.vseepreview.com/files/view/5e15d150-19b4-4cbd-b217-332fc71b6977?auth_code=e86ceb8b57c91e4db41611f08311a125e2df0b09&time=1578488144", "meta": { "category": "user_document", "target": { "id": "350936", "type": "user" }, "account": { "code": "vclinic" } }, "creator": { "id": "350936", "username": "test+member01@test.com", "email": "test+member01@test.com", "full_name": "Test User" } } } ``` ### GET /files URL: https://developers.vsee.io/api/file-upload-api/get/files Auth: User Token — Requires a user access token from login or SSO. List files Retrieve list of files with optional filtering Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - target_id (query, string, optional) — The ID of the target (user_id or visit_id) - target_type (query, string, optional) — Target type (user or visit) [enum: user, visit] - category_type (query, string, optional) — File category type (user_document, intake_attachment, user_consent, user_avatar) - include_shared (query, boolean, optional) — Include shared files Responses: - 200 — Successful response ```json { "data": [ { "created": 1657668358, "creator": { "full_name": "Patient's Name", "type": 200, "username": "62ce09a2940adc6474" }, "ext": "pdf", "fullpath": "https://api-vclinic.vsee.me/files/view/62ce0306-bd68-8fj3-7771-6dfc0ks8219474?auth_code=bb7e2d413f9jd93unf92u4e35584d10&time=1669924552", "id": "62ce0306-bd68-8fj3-7771-6dfc0ks8219474", "is_deletable": true, "meta": { "account": { "code": "vclinic" }, "category": "user_document", "target": { "id": "2317820300", "type": "user" } }, "name": "2017-01-21 04:00:00 - filename.pdf", "size": 274988 } ] } ``` ### GET /files/{id} URL: https://developers.vsee.io/api/file-upload-api/get/files/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Get file info Retrieve file information including download link Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — File ID Responses: - 200 — Successful response ```json { "data": { "id": "57e8c9a2-5c30-4b2c-b9d0-11d6ac1f0144", "name": "Screenshot 2023-02-22 at 21.47.43.png", "size": 25473, "ext": "png", "fullpath": "https://api-vclinic.vsee.me/files/view/57e8c9a2-5c30-4b2c-b9d0-11d6ac1f0144?auth_code=01f72b633c40c73a87f1bc66694ee31&time=1677099046", "meta": { "target": { "id": "63f67fb0-9864-4059-ad1b-63b10adc6474", "type": "intake" }, "category": "intake_attachment", "account": { "code": "vclinic" } }, "creator": { "username": "anton+test2@vseelab.com", "type": 200, "full_name": "anton test_2", "id": "27769243" }, "created": 1677098901 } } ``` ### POST /files/{id} URL: https://developers.vsee.io/api/file-upload-api/post/files/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Update file info Modify file information (name, title, description) Currently only the `name` field can be modified (deprecated in favor of `meta.title` — coming soon). Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — File ID Request body (application/x-www-form-urlencoded): - name (string, optional) — File name - meta.title (string, optional) — File title - meta.description (string, optional) — File description Example request: ```json { "name": "string", "meta.title": "string", "meta.description": "string" } ``` Responses: - 200 — Successful update ```json { "data": { "id": "5e1598e7-4118-47ca-84da-0923c71b6977", "name": "test2.jpg", "size": 184259, "ext": "jpg", "meta": { "target": { "id": "350936", "type": "user" }, "category": "user_document" } } } ``` ### DELETE /files/{id} URL: https://developers.vsee.io/api/file-upload-api/delete/files/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Delete file Delete a file Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — File ID Responses: - 200 — Successful deletion ```json { "data": true } ``` ### GET /files/view/{id} URL: https://developers.vsee.io/api/file-upload-api/get/files/view/%7Bid%7D Auth: User Token — Requires a user access token from login or SSO. Download file Download the file content. Parameters available for authenticated access. **Note:** The file view URL includes an `auth_code` and `time` parameter for secure, time-limited access. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — File ID - auth_code (query, string, optional) — Authentication code from file info response - time (query, string, optional) — Timestamp from file info response - size (query, string, optional) — Optional resized image dimensions (WxH format, e.g. 320x240) Responses: - 200 — File content ```json binary ``` ## Slot API Landing: https://developers.vsee.io/api/slot-api · Spec JSON: https://developers.vsee.io/specs/slot_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 The Slot API provides time slot availability for scheduling appointments. Slots are defined by providers and represent available time windows for patient bookings. ### GET /slots URL: https://developers.vsee.io/api/slot-api/get/slots operationId: listSlots Auth: User Token — Requires a user access token from login or SSO. List slots Retrieve a list of slots with optional filtering by various criteria Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - start (query, integer, required) — UNIX timestamp for start of range - end (query, integer, required) — UNIX timestamp for end of range - status (query, integer, optional) — Filter by status. Use 10 for open slots - type (query, string, optional) — Type of slot [enum: one, group] - provider_id (query, string, optional) — Filter by provider ID - room_code (query, string, optional) — Filter by room code - account_code (query, string, optional) — Filter by account code - specialty_id (query, string, optional) — Filter by specialty ID - states_serviced (query, string, optional) — Filter by states serviced Responses: - 200 — List of slots ```json { "data": [ { "id": "63850640-129c-4e8a-af18-0b9f0a7d64b7", "provider_id": "9046", "account_code": "bac-team", "start": 1669836600, "end": 1669838400, "group_id": "63850640-2cf0-4822-a0bc-0b9f0a7d64b7", "status": 10, "modified": 1669662272, "created": 1669662272, "group": { "id": "63850640-2cf0-4822-a0bc-0b9f0a7d64b7", "date_start": "1669827600", "date_end": "1669913999", "time_start": "1669836600", "time_end": "1669838400", "repeat": false, "repeat_day": [], "repeat_week": 1, "account_code": "bac-team", "provider_id": "9046", "visit_type": "group", "timezone": "Asia/Ho_Chi_Minh" }, "provider": { "id": "9046", "username": "bac+provider3@vseelab.com", "email": "bac+provider3@vseelab.com", "vseeid": "bac+provider3@vseelab.com", "full_name": "Bac Provider3 (edited)" } } ] } ``` ### GET /slots/available URL: https://developers.vsee.io/api/slot-api/get/slots/available operationId: getAvailableSlots Auth: User Token — Requires a user access token from login or SSO. Get available slots Retrieve available slots for booking Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Responses: - 200 — Available slots ```json { "data": [ { "id": "string", "provider_id": "string", "account_code": "string", "start": 0, "end": 0, "group_id": "string", "status": 0, "modified": 0, "created": 0, "group": { "id": "string", "date_start": "string", "date_end": "string", "time_start": "string", "time_end": "string", "repeat": true, "repeat_day": [ "string" ], "repeat_week": 0, "account_code": "string", "provider_id": "string", "visit_type": "string", "consultation": { "id": "string", "description": "string", "duration": 0, "charge": true, "group": true, "slots": 0, "amount": 0, "visible_to_patient": true }, "timezone": "string", "modified": 0, "created": 0 }, "provider": { "id": "string", "username": "string", "email": "string", "vseeid": "string", "full_name": "string", "specialties": [ "string" ], "states_serviced": [ "string" ], "clinics": [ "string" ], "rooms": [ { "id": "string", "code": "string", "name": "string", "slug": "string", "domain": "string", "account_code": "string" } ] }, "account": { "id": "string", "name": "string", "domain": "string", "code": "string" } } ] } ``` ### DELETE /slots/{id} URL: https://developers.vsee.io/api/slot-api/delete/slots/%7Bid%7D operationId: deleteSlot Auth: User Token — Requires a user access token from login or SSO. Delete slot Delete a single slot by ID Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Slot ID Responses: - 200 — Slot deleted successfully ```json { "data": { "slot_deleted": 1, "group_deleted": 1 } } ``` ### DELETE /slots/groups/{groupId} URL: https://developers.vsee.io/api/slot-api/delete/slots/groups/%7BgroupId%7D operationId: deleteSlotGroup Auth: User Token — Requires a user access token from login or SSO. Delete slot group Delete a slot group and all associated slots Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - groupId (path, string, required) — Slot group ID Responses: - 200 — Slot group deleted successfully ```json { "data": { "slot_deleted": 2, "group_deleted": 1 } } ``` ## Recordings API Landing: https://developers.vsee.io/api/recordings-api · Spec JSON: https://developers.vsee.io/specs/recordings_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 The Recordings API uses the Visit API endpoints with special parameters to access visit recordings. **Key:** Include `recordings` in the `fields` parameter of GET /visits to receive recording objects. Use `with_recordings_only=1` to filter out visits without recordings. Recording download URLs (`path.url`) are pre-signed S3 URLs with a time-limited expiry (`path.expiry`). ### GET /visits URL: https://developers.vsee.io/api/recordings-api/get/visits operationId: listVisitsWithRecordings Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App). List visits with recordings Retrieve a list of visits with recordings within a specified time range Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - room_code (query, string, optional) — Room's code to filter visits - start_time (query, integer, optional) — UNIX timestamp — filter visits starting after this time - end_time (query, integer, optional) — UNIX timestamp — filter visits ending before this time - fields (query, string, optional) — Comma-separated list of field names to include in response. Use 'recordings' to include recording objects - with_recordings_only (query, integer, optional) — Set to `1` to only return visits that have recordings. [enum: 0, 1] Responses: - 200 — List of visits with recordings ```json { "data": [ { "id": "82828", "start": 1631628616, "end": 1631628916, "actual_start": 1631628211, "actual_end": null, "hosts": [], "type": 2, "status": 30, "meeting": { "recording_auto_start": false, "phone_numbers": { "US": [ "+1.650.758.0255" ] }, "hosts": [ "anton+providersa@vseelab.com", "chau+provider@vseelab.com" ], "expiry": 1633643316, "conference_pin": 838759, "meeting_id": "1633627695040_2cc263f4-3d07-49fa-97b1-b2955ff40dfa__jitsi" }, "recordings": { "count": 1, "data": [ { "id": 111, "visit_id": "82828", "end": 1633966813, "start": 1633966696, "version": 3, "participants": [ { "first_name": "Keven2", "last_name": "Teodoro2", "vseeid": "conciergedev+user575" }, { "first_name": "Keven2", "last_name": "Teodoro2", "vseeid": "provider.w@vclinic.com" } ] } ] } } ] } ``` ### GET /visits/{id}/recordings/{recording_id} URL: https://developers.vsee.io/api/recordings-api/get/visits/%7Bid%7D/recordings/%7Brecording_id%7D operationId: getRecording Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App). Get recording Retrieve a specific recording with download URL Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code - id (path, string, required) — Visit ID - recording_id (path, string, required) — Recording ID from visits.data.recordings.id Responses: - 200 — Recording details with download URL ```json { "id": 111, "visit_id": 82828, "end": 1633966813, "start": 1633966696, "version": 3, "participants": [ { "first_name": "Keven2", "last_name": "Teodoro2", "vseeid": "conciergedev+user575" }, { "first_name": "Keven2", "last_name": "Teodoro2", "vseeid": "provider.w@vclinic.com" } ], "path": { "url": "https://recordings-bucket.example-s3.amazonaws.com/EXAMPLE_CLINIC/1636431607681_recording__example.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20211112T151817Z&X-Amz-SignedHeaders=host&X-Amz-Expires=14400&X-Amz-Credential=EXAMPLEACCESSKEYID123%2F20211112%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=EXAMPLESIGNATUREdonotusethisvalueitisaplaceholder00000000", "expiry": 1634966813 } } ``` ## Survey API Landing: https://developers.vsee.io/api/survey-api · Spec JSON: https://developers.vsee.io/specs/survey_api_openapi.json Base URL: https://api-ms.vsee.me/api ### GET /surveys/{survey_code}/responses URL: https://developers.vsee.io/api/survey-api/get/surveys/%7Bsurvey_code%7D/responses operationId: getSurveyResponses Auth: User Token — Requires a user access token from login or SSO. Get survey responses Retrieve survey responses based on survey code and optional filters Parameters: - X-ApiToken (header, string, required) — API token - survey_code (path, string, required) — Survey code to filter responses. Use 'all' to retrieve all surveys [enum: all, cancel_intake_survey, provider_visit_survey, cancel_call_survey, post_visit_survey] - from_time (query, integer, optional) — UNIX timestamp for start of search period - to_time (query, integer, optional) — UNIX timestamp for end of search period - clinic_codes (query, string, optional) — Comma-separated list of clinic codes to filter - visit_ids (query, string, optional) — Comma-separated list of visit IDs to filter Responses: - 200 — Survey responses retrieved successfully ```json { "data": [ { "id": "62685d75-b290-4e71-9bf6-33e464457b11", "survey_code": "cancel_call_survey", "clinic_code": "vclinic", "visit_id": "22183940", "intake_id": "", "room_code": "", "user_id": "16811538", "data": { "reason": "test_call", "member_id": "21728487", "provider_id": "0" }, "created": 1651006837 } ], "total_count": 1131 } ``` ## Health API (Beta) Landing: https://developers.vsee.io/api/health-api · Spec JSON: https://developers.vsee.io/specs/health_api_openapi.json Base URL: https://api.vseepreview.com/api_v3 Health data and device management API ### POST /users/{user_id}/devices URL: https://developers.vsee.io/api/health-api/post/users/%7Buser_id%7D/devices operationId: registerDevice Auth: User Token — Requires a user access token from login or SSO. Register device Register a health monitoring device for a user Parameters: - X-ApiToken (header, string, required) — API token - X-ApiKey (header, string, required) — API Key - X-AccountCode (header, string, required) — Account code - user_id (path, string, required) — User ID Request body (application/json): - device_id (string, required) — Device unique identifier - device_name (string, required) — Human-readable device name - type (string, required) — Device type code [enum: ihealth_po_po3, ihealth_scale_hs2, applehealth, samsunghealth, welchallync_bp_bp100, ihealth_bg_bg5s, ihealth_thermometer_pt3sbt] Example request: ```json { "device_id": "004D320DCAA2", "device_name": "Thermometer PT3SBT", "type": "ihealth_thermometer_pt3sbt" } ``` Responses: - 200 — Device registered successfully ```json { "data": { "device_id": "string", "device_name": "string", "type": "string", "user_id": "string", "created_at": 0 } } ``` ### POST /health URL: https://developers.vsee.io/api/health-api/post/health operationId: submitHealthData Auth: User Token — Requires a user access token from login or SSO. Submit health data Submit health measurement data from a registered device Parameters: - X-ApiToken (header, string, required) — API token - X-ApiKey (header, string, required) — API Key - X-AccountCode (header, string, required) — Account code Request body (application/json): - type (string, required) — Device type - date (string, required) — Date in YYYY-MM-DD format - time (integer, required) — UNIX timestamp - device_id (string, required) — Device unique identifier - data_type (string, required) — Type of measurement [enum: temperature_body, bg, bp, weight, active_minutes, steps, hr, bo, illuminance, humidity, gas, movement, noise, range] - data_class (string, required) — Data classification [enum: body, environment] - temperature_body (string, optional) — Body temperature value - temperature_unit (string, optional) — Temperature unit [enum: cel, fah] - bg (number, optional) — Blood glucose value - bg_unit (string, optional) — Blood glucose unit [enum: mg/dL, mmol/L] - hp (integer, optional) — Systolic blood pressure (high pressure) - lp (integer, optional) — Diastolic blood pressure (low pressure) - bp_unit (string, optional) — Blood pressure unit [enum: mmHg, kPa] - weight (number, optional) — Weight value - weight_unit (string, optional) — Weight unit [enum: lbs, kg] - active_minutes (integer, optional) — Active minutes - steps (integer, optional) — Step count - hr (number, optional) — Heart rate - bo (number, optional) — Blood oxygen - illuminance (number, optional) — Illuminance value - illuminance_unit (string, optional) — Illuminance unit [enum: lux] - humidity (number, optional) — Humidity value - humidity_unit (string, optional) — Humidity unit [enum: percentage] - gas (string, optional) — Gas value - movement (, optional) — Movement value - noise (number, optional) — Noise level - noise_unit (string, optional) - range (number, optional) — Range in cm - range_unit (string, optional) — Range unit [enum: cm] Example request: ```json { "type": "ihealth_thermometer_pt3sbt", "date": "2021-08-25", "time": 1695626540, "device_id": "004D320DCAA2", "data_type": "temperature_body", "data_class": "body", "temperature_body": "36.76", "temperature_unit": "cel" } ``` Responses: - 200 — Health data submitted successfully ```json { "data": { "id": "string", "status": "string" } } ``` ## Webhooks Landing: https://developers.vsee.io/api/webhooks · Spec JSON: https://developers.vsee.io/specs/webhooks_openapi.json Base URL: https://api.vseepreview.com/api_v3 Webhook event documentation for VSee Clinic API ### POST /webhooks/events URL: https://developers.vsee.io/api/webhooks/post/webhooks/events operationId: webhookEvent Auth: Admin Token — Requires the Clinic Admin API Token from your dashboard (Developers → App → Edit App). Webhook event Webhook events are sent to your configured webhook URL. This documents the available event types and their payloads. Parameters: - X-ApiToken (header, string, required) — API token - X-AccountCode (header, string, required) — Account code Request body (application/json): Example request: ```json { "version": "1.0", "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "visit.created", "created": 1546950556, "account_code": "xxx", "data": { "id": "28540", "member_id": "60610", "provider_id": null, "start": "1546950546", "end": "1546951446", "actual_start": "1546950546", "actual_end": "1546950555", "status": "scheduled", "completed_by": "60610" } } ``` Responses: - 200 — Webhook received successfully