Patient use case

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.

Steps

1. 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:

   Field	Required	Description
   X-ApiKey	yes	API Key
   X-ApiSecret	yes	API Secret
   X-AccountCode	yes	Account code

   queryParams:

   Field	Required	Description
   fields	no	Set to 'vsee' to include VSee ID and token

   bodyFields:

   Field	Required	Description
   first_name	yes	Patient's first name
   last_name	yes	Patient's last name
   type	yes	User type: 200 = Patient
   email	no	Patient email address
   code	yes	Unique patient identifier on your end (max 128 chars)

2. 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:

   Field	Required	Description
   X-AccountCode	yes	Account code

   pathParams:

   Field	Required	Description
   room_code	yes	Waiting room code (e.g., sandbox)

3. 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:

   Field	Required	Description
   X-ApiToken	yes	User access token from SSO response
   X-AccountCode	yes	Account code

   bodyFields:

   Field	Required	Description
   type	yes	Intake type (1 = standard)
   room_code	yes	Room code for the waiting room
   reason_for_visit	no	Reason for visit / chief complaint

4. 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:

   Field	Required	Description
   X-ApiToken	yes	User access token from SSO response
   X-AccountCode	yes	Account code

   queryParams:

   Field	Required	Description
   member_id	yes	Provider's VSee member ID (auto-fills from stored Provider Member ID)
   start	yes	Search window start (Unix timestamp — defaults to now)
   end	yes	Search window end (Unix timestamp — defaults to now + 7 days)
   duration	yes	Slot duration in seconds
   consultation_id	yes	Consultation ID from Step 2
   intake_id	yes	Intake ID from Step 3

5. 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:

   Field	Required	Description
   X-ApiToken	yes	User access token from SSO response
   X-AccountCode	yes	Account code

   bodyFields:

   Field	Required	Description
   member_id	yes	Provider's VSee member ID (same as Step 4 — auto-fills from stored Provider Member ID)
   intake_id	yes	Intake ID from Step 3
   room_code	yes	Room code
   slot_start	yes	Start time from Step 4 (Unix timestamp)
   slot_end	yes	End time from Step 4 (Unix timestamp)
   type	yes	Visit type: 2 = scheduled

6. Step 6: Build appointment link

   Redirect to 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.