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