# 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"
}
```