{ "openapi": "3.0.3", "info": { "title": "Insurance API", "version": "3.0", "contact": { "email": "admin@vsee.com" }, "description": "\n\nThe insurance CRUD APIs can be called using either a patient's token or a Clinic Admin token.\n\nInsurance 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." }, "servers": [ { "url": "https://api.vseepreview.com/api_v3", "description": "Staging" } ], "x-readme": { "explorer-enabled": false, "proxy-enabled": false, "samples-languages": [ "curl", "python", "javascript", "java" ] }, "tags": [ { "name": "Insurance", "description": "Insurance card management" }, { "name": "Eligibility", "description": "Insurance eligibility checks" }, { "name": "Claims", "description": "Claims reporting and retrieval" }, { "name": "Reference", "description": "Reference data lists" } ], "paths": { "/users/{user_id}/insurances": { "get": { "tags": [ "Insurance" ], "summary": "List insurance cards", "description": "Retrieve a list of insurance cards associated with a user", "operationId": "listInsurances", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID" } ], "responses": { "200": { "description": "List of insurance cards", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsuranceCard" } }, "version": { "type": "string" } } }, "examples": { "success": { "value": { "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" } } } } } } }, "x-auth-type": "user-token" } }, "/users/{user_id}/insurances/import": { "post": { "tags": [ "Insurance" ], "summary": "Import insurance cards", "description": "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.", "operationId": "importInsurances", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "insurances": { "type": "array", "items": { "$ref": "#/components/schemas/InsuranceCard" } } }, "required": [ "insurances" ] }, "examples": { "import": { "value": { "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": { "description": "Insurances imported successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsuranceCard" } }, "version": { "type": "string" } } }, "examples": { "success": { "value": { "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" } } } } } } }, "x-auth-type": "user-token" } }, "/users/{user_id}/insurances/{card_type}": { "post": { "tags": [ "Insurance" ], "summary": "Update insurance", "description": "Update primary or secondary insurance details for a user", "operationId": "updateInsurance", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "card_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "primary", "secondary" ] }, "description": "Insurance card type" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsuranceCard" }, "examples": { "update": { "value": { "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": { "description": "Insurance updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsuranceCard" }, "version": { "type": "string" } } }, "examples": { "success": { "value": { "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" } } } } } } }, "x-auth-type": "user-token" }, "get": { "tags": [ "Insurance" ], "summary": "Get insurance", "description": "Retrieve primary or secondary insurance details for a user", "operationId": "getInsurance", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "card_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "primary", "secondary" ] }, "description": "Insurance card type" } ], "responses": { "200": { "description": "Insurance details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsuranceCard" }, "version": { "type": "string" } } }, "examples": { "success": { "value": { "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" } } } } } } }, "x-auth-type": "user-token" }, "delete": { "tags": [ "Insurance" ], "summary": "Delete insurance", "description": "Delete primary or secondary insurance for a user", "operationId": "deleteInsurance", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "card_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "primary", "secondary" ] }, "description": "Insurance card type" } ], "responses": { "204": { "description": "Insurance deleted successfully" } }, "x-auth-type": "user-token" } }, "/users/{user_id}/insurances/primary/eligibility/check": { "post": { "tags": [ "Eligibility" ], "summary": "Check eligibility", "description": "Check and return queue status and current eligibility status for primary insurance", "operationId": "checkEligibility", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID" } ], "responses": { "200": { "description": "Eligibility check initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string" } } } } }, "examples": { "pending": { "value": { "data": { "job_id": "6552fefa-e620-4caa-9990-26940a7d6499", "status": "pending" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "rateLimit": { "value": { "code": 429, "message": "Started at Tue, 14 Nov 2023 12:05:00 +0700" } } } } } } }, "x-auth-type": "user-token" } }, "/users/{user_id}/insurances/primary/eligibility": { "get": { "tags": [ "Eligibility" ], "summary": "Get eligibility status", "description": "Return queue status and current eligibility status for primary insurance", "operationId": "getEligibilityStatus", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID" } ], "responses": { "200": { "description": "Eligibility status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string" } } } } }, "examples": { "pending": { "value": { "data": { "job_id": "655300b4-2378-4ec7-98bf-34b50a7d6499", "status": "pending" } } }, "active": { "value": { "data": { "status": "active" } } } } } } } }, "x-auth-type": "user-token" } }, "/reports/claims": { "get": { "tags": [ "Claims" ], "summary": "List claims", "description": "Return list of visits with claim-relevant data", "operationId": "listClaims", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start date for claims report (YYYY-MM-DD format)" }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End date for claims report (YYYY-MM-DD format)" } ], "responses": { "200": { "description": "List of claims", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } } }, "x-auth-type": "user-token" } }, "/insurances/list/carriers": { "get": { "tags": [ "Reference" ], "summary": "List carriers", "description": "Retrieve list of insurance carriers", "operationId": "listCarriers", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "responses": { "200": { "description": "List of carriers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "advancedmd": { "type": "object" } } } } } }, "examples": { "success": { "value": { "data": [ { "name": "A AND I BENEFIT PLAN ADMINISTRATORS", "code": "AAND", "advancedmd": { "address": { "zip": "", "city": "", "state": "", "address1": "", "address2": "", "areacode": "UND" }, "cpid": "3296", "code": "car7339" } } ] } } } } } } }, "x-auth-type": "user-token" } }, "/insurances/list/insurers": { "get": { "tags": [ "Reference" ], "summary": "List insurers", "description": "Retrieve list of insurers", "operationId": "listInsurers", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "responses": { "200": { "description": "List of insurers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "description": { "type": "string" } } } } } }, "examples": { "success": { "value": { "data": [ { "id": "AAND", "text": "A AND I BENEFIT ADMINISTRATORS", "description": "A AND I BENEFIT ADMINISTRATORS" }, { "id": "AARP", "text": "AARP", "description": "AARP" } ] } } } } } } }, "x-auth-type": "user-token" } }, "/insurances/list/billing_modifiers": { "get": { "tags": [ "Reference" ], "summary": "List billing modifiers", "description": "Retrieve list of billing modifiers", "operationId": "listBillingModifiers", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "responses": { "200": { "description": "List of billing modifiers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "description": { "type": "string" } } } } } }, "examples": { "success": { "value": { "data": [ { "id": "20", "text": "20", "description": "20" }, { "id": "F8", "text": "F8", "description": "F8" } ] } } } } } } }, "x-auth-type": "user-token" } }, "/insurances/list/dxs": { "get": { "tags": [ "Reference" ], "summary": "List diagnoses", "description": "Retrieve list of diagnosis codes", "operationId": "listDiagnoses", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "responses": { "200": { "description": "List of diagnoses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "advancedmd": { "type": "object" } } } } } }, "examples": { "success": { "value": { "data": [ { "code": "I10", "description": "Essential (primary) hypertension", "advancedmd": { "code": "diag0010" } }, { "code": "E11.9", "description": "Type 2 diabetes mellitus without complications", "advancedmd": { "code": "diag0021" } } ] } } } } } } }, "x-auth-type": "user-token" } }, "/insurances/list/procedures": { "get": { "tags": [ "Reference" ], "summary": "List procedures", "description": "Retrieve list of procedures", "operationId": "listProcedures", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "responses": { "200": { "description": "List of procedures", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "description": { "type": "string" } } } } } }, "examples": { "success": { "value": { "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" } ] } } } } } } }, "x-auth-type": "user-token" } } }, "components": { "schemas": { "InsuranceCard": { "type": "object", "properties": { "card_type": { "type": "string", "enum": [ "primary", "secondary" ] }, "insurer_code": { "type": "string" }, "subscriber_number": { "type": "string" }, "subscriber_num": { "type": "string" }, "group_number": { "type": "string" }, "responsible_party": { "type": "string" }, "guarantor_first_name": { "type": "string" }, "guarantor_middle_name": { "type": "string" }, "guarantor_last_name": { "type": "string" }, "guarantor_dob": { "type": "string", "format": "date" }, "guarantor_gender": { "type": "integer" }, "guarantor_address": { "type": "string" }, "guarantor_address_2": { "type": "string" }, "guarantor_city": { "type": "string" }, "guarantor_zip": { "type": "string" }, "guarantor_state": { "type": "string" }, "consent": { "type": "boolean" } } } } } }