Versions Compared

Old Version 16

changes.mady.by.user Anton Tolkachiov

Saved on

compared with

New Version Current

changes.mady.by.user Anton Tolkachiov

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Check Eligibility workflow

You have patient’s demographics information and patient’s insurance information.

You want to check if the patient is eligible for the procedure / visit.

  1. Contact the VSee team to configure which insurers you want to support. Once configured, use https://vsee.atlassian.net/wiki/spaces/VD/pages/55083127/Insurance+API+Draft#GET-%2Finsurance%2F to pull the list which will also contain insurer_id.

  2. The VSee Clinic user should already exist or you can create one via https://vsee.atlassian.net/wiki/spaces/VD/pages/14942243/User+API#POST-%2Fusers%2Fsso

  3. Some user fields are required if you want to use the insurance. Use https://vsee.atlassian.net/wiki/spaces/VD/pages/14942243/User+API#POST-%2Fme to update the user’s insurance information.

3. Run https://vsee.atlassian.net/wiki/spaces/VD/pages/55083127#POST-%2Fusers%2F%3Aid%2Feligibility to trigger the eligibility check.

4. Trigger a claim submission process https://vsee.atlassian.net/wiki/spaces/VD/pages/55083127/Insurance+API+Draft#POST-%2Finsurance%2Fclaims

POST /me parameters

Required Insurance Information

Code Block
FirstName - first_name
LastName - last_name
DOB - dob
Gender - gender
Address - street_addr
City - city
State - state
ZipCode - zip
Insurance - insurance.carrier (e.g. car7147 - AMD code)
InsuranceCoverage - insurance.respparty (e.g self, child, spouse, other)
standardrelationship
hipaarelationship

If dependent (child, spouse, other):
Guarantor Name - insurance.guarantor_name
Guarantor DOB  - insurance.guarantor_dob
Guarantor Address1 - insurance.guarantor_address
Guarantor City - insurance.guarantor_city
Guarantor State - insurance.guarantor_state
Guarantor Zip -  - insurance.guarantor_zip

POST /users/:id/eligibility

https://api-vclinic.vseepreview.com/vc/next/api_v3/users/:id/eligibility

Check insurance eligibility for the given patient. This assumes all required insurance data is saved for this user.

Set insurance data with https://vsee.atlassian.net/wiki/spaces/VD/pages/14942243/User+API#POST-%2Fme ? (insurer_id, insurance_plan).

VSee will create a patient record in AdvancedMD as needed if it’s not existing yet.

Input

...

Parameter Name

...

Type

...

Description

...

...

...

String

...

…

Result

Since the check may take up to 1-2 minutes, should we trigger a webhook eligibility.checked when it's ready?

Output

Code Block
{
  "data": {
      "eligibility_id": amd_eligibility_id
    }
}

In case of error / missing data we should display a proper error message.

Raw Data in user_datas

It will populate the user’s insurance.eligibility when response received from the 3rd party.

...

Create / update delete / retrieve insurance detail

Info

The following APIs can be called using patient’s token or Clinic Admin token

GET api_v3/users/:user_id/insurances
Status
colourYellow
titleV3

This returns a list of insurance cards associated with this user

Expand
titleResponse (200)
Code Block
languagejson
{
    "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
        },
        {
            "card_type": "secondary",
"eligibility
  "insurer_code":
{
 "(sandbox) CALIFORNIA MEDICAL",
            "
last
subscriber_
checked
num":
1640133254
"11000023",
            "
eligibility
responsible_
response
party": "child"
Invalid/Missing subscriber/insured ID",
,
            "
eligibility
guarantor_first_
text
name": "VSee",
            
"guarantor_last_name": "Patient 11000023",
            "
raw
guarantor_middle_
response
name": "Edward",
...
//TBD 
 "guarantor_dob": "1944-01-01",
}
}, }

Webhook

Code Block
{
"guarantor_gender": 2,
"id": "5c34979c-30dc-496c-8cd3-6eb9925862c1",
      "
type
guarantor_address": "
eligibility.checked
52 Rainbow St",
"created": 1546950556,
         "
account
guarantor_
code
city": "
vclinic
Sunnyvale",
"data":
{
        "
eligibility
guarantor_
id
zip": "
28540
10001",
            "
member
guarantor_
id
state": "
60610
CA",
"eligibility_response":
"Invalid/Missing
subscriber/insured
ID",
  "consent": true
"external_member_id": 1111
    }
}

Eligibility Responses List

eligibility_response may be one of the following:

Code Block
Success
Authorized
quantity
exceeded
Required
],
application
data
missing
Input
Errors Out of Network Authorization/Access restrictions Unable to respond at current time. Invalid/Missing provider information Invalid/Missing provider name Invalid/Missing provider speciality Invalid/Missing provider phone number Invalid/Missing provider state Invalid/Missing referring provider identification number Provider is not primary care physician Provider ineligible for inquiries Provider not on file Service dates not within provider plan enrollment Inquired benefit inconsistent with provider type Inappropriate date Invalid/Missing dates of service Invalid/Missing date of birth Date of birth follows date of service Date of death preceeds dates of service Date of service not within allowable inquiry period Date of service in future Invalid/Missing patient ID Invalid/Missing patient name Invalid/Missing patient gender code Patient not found Inconsistent with patient age. Inconsistent with patient gender. Patient birth date does not match that for the patient in the Invalid/Missing subscriber/insured ID Invalid/Missing subscriber/insured name Invalid/Missing subscriber/insured gender code Subscriber/Insured not found Duplicate Subscriber/Insured ID number Subscriber found, patient not found Subscriber/Insured not in Group/Plan identified Invalid participant identification invalid or missing provider address Payer name or identifier missing Certification Information Missing No response received by clearinghouse Expiremental service or procedure. Authorization number not found. Requires primary care physician authorization. Invalid/Missing diagnosis codes. Invalid/Missing procedure codes. Additional patient condition information required. Certification information does not match patient. Requires medical review. Invalid authorization number format. Missing authorization number.

GET /insurance/

https://api-vclinic.vseepreview.com/vc/next/api_v3/insurance/

Get the available list of insurers for patient to pick from.

Is it stored in clinic Raw settings.

Input

...

Parameter Name

...

Type

...

Description

Output

A list of supported insurers.

“id” here is AMD’s payer ID. “name” is readable name.

Code Block
{ "data": { "insurers": [ { "id": "car7147",
"version": "2.0"
}

POST api_v3/users/{user_id}/insurances/import
Status
colourYellow
titleV3

  • Payload should include array of up to 2 insurance detail, one is primary and the other is secondary

  • If insurance type already exists, it will be overwritten

Expand
titleRequest payload
Code Block
languagejson
{
    "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
        },
        {
            "
name
card_type": "
CIGNA
secondary",
}, 
   "insurer_code": "(sandbox) CALIFORNIA MEDICAL",
{
         "
id
subscriber_number": "
car7551
11000023",
            "
name
responsible_party": "
AETNA
child",
}
] }

POST /insurance/claims

https://api-vclinic.vseepreview.com/vc/next/api_v3/insurance/claims

Claims collection

Code Block
claims.type
claims.account_code
claims.visit_id //optional
claims.member_id
claims.status
claims.advancedmd.date_of_service // all input fields
claims.advancedmd.visit_id

Input

...

Parameter Name

...

Type

...

Description

...

visit_id

...

String

...

…

...

date_of_service

...

12/1/2021

...

location

...

41

...

procedure_code

...

U0003;U0005

...

units

...

1

...

diagnosis_code

...

Z20.822;R05.9

Output

Code Block
{ "data": {
 "guarantor_first_name": "VSee",
            "guarantor_last_name": "Patient 11000023",
            "guarantor_middle_name": "Edward",
            "guarantor_dob": "1944-01-01",
            "guarantor_gender": 2,
            "guarantor_address": "52 Rainbow St",
            "guarantor_city": "Sunnyvale",
            "guarantor_zip": "10001",
            "guarantor_state": "CA",
            "consent": true
        }
    ]
}
Expand
titleResponse (200)
Code Block
languagejson
{
    "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
        },
        {
            "card_type": "secondary",
            "insurer_code": "(sandbox) CALIFORNIA MEDICAL",
            "subscriber_number": "11000023",
            "responsible_party": "child",
            "guarantor_first_name": "VSee",
            "guarantor_last_name": "Patient 11000023",
            "guarantor_middle_name": "Edward",
            "guarantor_dob": "1944-01-01",
            "guarantor_gender": 2,
            "guarantor_address": "52 Rainbow St",
            "guarantor_city": "Sunnyvale",
            "guarantor_zip": "10001",
            "guarantor_state": "CA",
            "consent": true
        }
    ],
    "version": "2.0"
}

POST api_v3/users/{user_id}/insurances/{primary|secondary}
Status
colourYellow
titleV3

Update primary or secondary insurance

Expand
titleRequest payload
Code Block
languagejson
 {
    "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
}
Expand
titleResponse (200)
Code Block
languagejson
{
    "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 api_v3/users/{user_id}/insurances/{primary|secondary}
Status
colourYellow
titleV3

Retrieve primary or secondary insurance

Expand
titleResponse (200)
Code Block
languagejson
{
    "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 api_v3/users/{user_id}/insurances/{primary|secondary}
Status
colourYellow
titleV3

Expand
titleResponse (204)
Code Block
204 No Content

Eligibility check

POST api_v3/users/{user_id}/insurances/primary/eligibility/check
Status
colourYellow
titleV3

  • Check and return queue status and current eligibility status

Expand
titleResponse 1 (200 OK)
Code Block
languagejson
{
    "data": {
        "job_id": "6552fefa-e620-4caa-9990-26940a7d6499",
        "status": "pending"
    }
}
Expand
titleResponse 2 (429 Too Many Requests)
Code Block
languagejson
{
    "code": 429,
    "message": "Started at Tue, 14 Nov 2023 12:05:00 +0700"
}

GET api_v3/users/{user_id}/insurances/primary/eligibility
Status
colourYellow
titleV3

  • Return queue status and current eligibility status

Expand
titleResponse 1
Code Block
languagejson
{
    "data": {
        "job_id": "655300b4-2378-4ec7-98bf-34b50a7d6499",
        "status": "pending"
    }
}
Expand
titleResponse 2
Code Block
languagejson
{
    "data": {
        "status": "active"
    }
}

Claims Center

GET api_v3/reports/claims?from_date=2024-09-02&to_date=2024-09-05
Status
colourYellow
titleV3

  • Return list of visits with other data that is relevant for claim

Retrieve data list

GET api_v3/insurances/list/insurers

Sample request

Code Block
languagebash
curl --location 'https://api-vclinic.vseepreview.com/vc/stable/api_v3/insurances/list/insurers' \
--header 'X-AccountCode: vclinic'

Sample response

Expand
titleResponse
Code Block
languagejson
{
	"data": [
		{
			"id": "AAND",
			"text": "A AND I BENEFIT ADMINISTRATORS",
			"description": "A AND I BENEFIT ADMINISTRATORS"
		}, {
			"id": "AGADM",
			"text": "A G ADMINISTRATORS LLC",
			"description": "A G ADMINISTRATORS LLC"
		}, {
			"id": "AAGA",
			"text": "AAG AMERICAN ADMINISTRATIVE GRP",
			"description": "AAG AMERICAN ADMINISTRATIVE GRP"
		}, {
			"id": "AAGG",
			"text": "AAG GALLAGHER BENEFITS",
			"description": "AAG GALLAGHER BENEFITS"
		}, {
			"id": "AARP",
			"text": "AARP",
			"description": "AARP"
		}
	]
}

GET api_v3/insurances/list/billing_modifiers

Sample request

Code Block
languagebash
curl --location 'https://api-vclinic.vseepreview.com/vc/stable/api_v3/insurances/list/billing_modifiers' \
--header 'X-AccountCode: vclinic'

Sample response

Expand
titleResponse
Code Block
languagejson
{
	"data": [
		{
			"id": "20",
			"text": "20",
			"description": "20"
		}, {
			"id": "F8",
			"text": "F8",
			"description": "F8"
		}, {
			"id": "LC",
			"text": "LC",
			"description": "LC"
		}, {
			"id": "T5",
			"text": "T5",
			"description": "T5"
		}, {
			"id": "XP",
			"text": "XP",
			"description": "XP"
		}
	]
}

GET api_v3/insurances/list/dxs

Sample request

Code Block
languagebash
curl --location 'https://api-vclinic.vseepreview.com/vc/stable/api_v3/insurances/list/dxs' \
--header 'X-AccountCode: vclinic'

Sample response

Expand
Code Block
languagejson
{
	"data": [
		{
			"code": "I10",
			"description": "Essential (primary) hypertension",
			"advancedmd": {
				"code": "diag0010"
			}
		},
		{
			"code": "E11.9",
			"description": "Type 2 diabetes mellitus without complications",
			"advancedmd": {
				"code": "diag0021"
			}
		}
	]
}

GET api_v3/insurances/list/procedures

Sample request

Code Block
languagebash
curl --location 'https://api-vclinic.vseepreview.com/vc/stable/api_v3/insurances/list/procedures' \
--header 'X-AccountCode: vclinic'

Sample response

Expand
Code Block
languagejson
{
  "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"
    },
    {
      "id": "10003",
      "text": "DIAGNOSTIC EVALUATION - LAB TEST REVIEW",
      "description": "Evaluation session for discussing lab test results with the patient"
    },
    {
      "id": "
82828
10004",
}
}

Webhook

Code Block
{
  
"
id
text": "
5c34979c-30dc-496c-8cd3-6eb9925862c1",
TELEHEALTH CONSULT - MINOR ISSUES",
      "
type
description": "
claims.updated", "visit_id": 1546950556,
Remote consultation for addressing minor health concerns"
"account_code": "vclinic"
 },
"data":
 {
      
"
claim_
id": "
28540
10005",

      "
member_id
text": "
60610
EXTENDED CONSULTATION - TREATMENT PLANNING",

      "
status
description": "Extended session for planning and discussing long-term treatment options"
    }
  ]
}