Sample clinic raw settings
{ "claims": { "enabled": true, "carrier": { "Cigna": "car7556", "Anthem Blue Cross Blue Shield": "car11406", "ANTHEM BLUE SHIELD": "car11406", "MONTGOMERY HEALTH INSURANCE": "car7580", "HEALTH CHOICE ARIZONA": "car7556", "MEDICAID LOUISIANA": "car11400" }, "relationship": { "self": { "standardrelationship": "1", "hipaarelationship": "18" }, "spouse": { "standardrelationship": "2", "hipaarelationship": "01" }, "child": { "standardrelationship": "3", "hipaarelationship": "19" }, "other": { "standardrelationship": "4", "hipaarelationship": "G8" } }, "procedure_codes": { "10022": { "id": "pcode35772", "units": "1.0", "tos": "01", "pos": "11", "fee": "30" }, "99211": { "id": "pcode35602", "units": "1.0", "tos": "01", "pos": "11", "fee": "28" }, "1035F": { "id": "pcode100247", "units": "1.0", "tos": "01", "pos": "11", "fee": "29" } }, "diagnosis_codes": { "Z20-822": "dcode1033895691", "R05-9": "dcode1033895692", "R50-9": "dcode1033894809", "R51-9": "dcode1033895693", "B34-9": "dcode1033895695" }, "proc_code_modifiers": { "20": "mcode2", "21": "mcode3", "F1": "mcode43" }, "facility_code": { "3": "fac94", "41": "fac94", "AWC": "fac95", "AMC": "fac230", "MSC": "fac3", "STM": "fac94" }, "default": { "provider_profile": "prof18", "finclass": "fclass4", "chart": "AUTO", "coverage": "1", "eligibilitystc": "30", "accttype": "4", "cron_job_delay": 20 }, "advancedmd": { "login_url": "xxx", "username": "xxx", "password": "xxx", "office_code": "xxx", "app_name": "xxx" } } }
Check Eligibility and Claims Submission 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.
Steps | Example Request | Example Response | |
---|---|---|---|
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#GET-%2Finsurance%2F to pull the list which will also contain insurer_id. | curl --location --request GET 'https://api-vclinic.vseepreview.com/vc/dev/api_v3/insurances/' \ --header 'X-ApiToken: xxxx' | { "data": { "insurers": [ { "id": "car7551", "name": "AETNA" }, { "id": "car7414", "name": "AETNA BETTER HEALTH OF ILLINOIS" }, { "id": "car11406", "name": "ANTHEM BLUE SHIELD" }, { "id": "car7147", "name": "CIGNA HEALTH CARE" }, { "id": "car7580", "name": "MONTGOMERY HEALTH INSURANCE" }, { "id": "car7556", "name": "HEALTH CHOICE ARIZONA" } ] } } |
2 | Create a VSee Clinic user via https://vsee.atlassian.net/wiki/spaces/VD/pages/14942243/User+API#POST-%2Fusers%2Fsso
| curl --location --request POST 'https://api-vclinic.vseepreview.com/vc/dev/api_v3/users/sso' \ --header 'X-AccountCode: vclinic' \ --header 'X-ApiKey: xxx' \ --header 'X-ApiSecret: xxx' \ --header 'X-ApiToken: xxx' \ --form 'first_name="Edward"' \ --form 'last_name="VSee"' \ --form 'type="200"' \ --form 'code="edward+001.vclinic@vseelab.com"' \ --form 'email="edward+001.vclinic@vseelab.com"' \ --form 'dob="1986-01-01"' \ --form 'gender="1"' \ --form 'street_addr="2868 Tully Street"' \ --form 'state="Detroit"' \ --form 'city="MI"' \ --form 'zip="48226"' | { "data": { "id": "132407", "code": "edward+001.vclinic@vseelab.com", "first_name": "Edward", "last_name": "VSee", "full_name": "Edward VSee", "username": "edward+001.vclinic@vseelab.com", "vseeid": "ccpreview+6258012d656449b8b5e73ad964457b1f", "dob": "1986-01-01", "email": "edward+001.vclinic@vseelab.com", "gender": 1, "active": true, "tos": false, "status": 20, "subtype": "", "street_addr": "2868 Tully Street", "state": "Detroit", "city": "MI", "zip": "48226", "timezone": "America/Los_Angeles", "email_verified": true, "account_code": "vclinic", "clinics": [ "vclinic" ], "created": 1649934637, "token": { "user_id": "132407", "token": "xxxx", "expiry": 1650021037, "created": 1649934637, "user_type": "200", "refresh_token": { "user_id": "132407", "token": "xxxx", "expiry": 1652526637, "created": 1649934637 } } } } |
3 | Some user fields are required if you want to use the insurance API. Use https://vsee.atlassian.net/wiki/spaces/VD/pages/14942243/User+API#POST-%2Fme to update the user’s insurance information based on user_id. | curl --location --request POST 'https://api-vclinic.vseepreview.com/vc/dev/api_v3/me.json' \ --header 'X-ApiToken: xxxx' \ --form 'insurance.primary_carrier_code="car7556"' \ --form 'insurance.respparty="self"' \ --form 'insurance.primary_subscriber_num="234234"' \ --form 'insurance.primary_group_number="test 3"' \ --form 'insurance.secondary_carrier_code="car11406"' \ --form 'insurance.secondary_group_number="asdasd"' \ --form 'insurance.secondary_subscriber_num="aaaaa"' | { "data": { "id": "132407", "code": "edward+001.vclinic@vseelab.com", "first_name": "Edward", "last_name": "VSee", "full_name": "Edward VSee", "username": "edward+001.vclinic@vseelab.com", "vseeid": "ccpreview+6258012d656449b8b5e73ad964457b1f", "dob": "1986-01-01", "email": "edward+001.vclinic@vseelab.com", "gender": 1, "active": true, "tos": false, "status": 20, "subtype": "", "street_addr": "2868 Tully Street", "state": "Detroit", "city": "MI", "zip": "48226", "timezone": "America/Los_Angeles", "email_verified": true, "insurance": { "primary": { "carrier_code": "car7556", "subscriber_num": "234234", "insurance_order": 1 }, "secondary": { "carrier_code": "car11406", "group_number": "asdasd", "subscriber_num": "aaaaa", "insurance_order": 2 }, "patient": { "respparty": "self" } }, "account_code": "vclinic", "clinics": [ "vclinic" ], "created": 1649934637 } } |
4 | Run Insurance API (Draft) | POST-/users/:id/:carrier_code/eligibility to trigger the eligibility check for the given user_id. The eligibility check may take some time. | curl --location --request POST 'https://api-vclinic.vseepreview.com/vc/dev/api_v3/users/132407/car7556/eligibility' \ --header 'X-AccountCode: vclinic' \ --header 'X-ApiToken: xxxx' | { "data": { "eligibility_id": "2505465", "carrier_code": "car7556" } } |
5 | Receive a webhook request with eligibility_response message which will contain the result of the eligibility check. | { "id": "62583ab3-8cfc-4a47-b6c9-272850e631f8", "type": "eligibility.checked", "created": 1649949363, "account_code": "vclinic", "data": { "eligibility_id": "2505464", "member_id": "132407", "eligibility_response": "No response received by clearinghouse", "external_member_id": "5991794" } } | |
6 | If the user is eligible, trigger a claim submission process for the user_id https://vsee.atlassian.net/wiki/spaces/VD/pages/55083127#POST-%2Finsurance%2Fclaims | TDB | TBD |
7 | Receive a webhook request which will contain the result of the claim. | TBD | TBD |
POST /me
https://api-vclinic.vseepreview.com/vc/dev/api_v3/me.json
Setup the required patient insurance information for eligibility check.
Request | Response |
---|---|
curl --location --request POST 'https://api-vclinic.vseepreview.com/vc/dev/api_v3/me.json' \ --header 'X-ApiToken: xxxx' \ --form 'insurance.primary_carrier_code="car7556"' \ --form 'insurance.respparty="self"' \ --form 'insurance.primary_subscriber_num="234234"' \ --form 'insurance.group_number="test 3"' \ --form 'insurance.secondary_carrier_code="car11406"' \ --form 'insurance.secondary_group_number="asdasd"' \ --form 'insurance.secondary_subscriber_num="aaaaa"' | { "data": { "id": "132407", "code": "edward+001.vclinic@vseelab.com", "first_name": "Edward", "last_name": "VSee", "full_name": "Edward VSee", "username": "edward+001.vclinic@vseelab.com", "vseeid": "ccpreview+6258012d656449b8b5e73ad964457b1f", "dob": "1986-01-01", "email": "edward+001.vclinic@vseelab.com", "gender": 1, "active": true, "tos": false, "status": 20, "subtype": "", "street_addr": "2868 Tully Street", "state": "Detroit", "city": "MI", "zip": "48226", "timezone": "America/Los_Angeles", "email_verified": true, "insurance": { "primary": { "carrier_code": "car7556", "subscriber_num": "234234", "insurance_order": 1 }, "secondary": { "carrier_code": "car11406", "group_number": "asdasd", "subscriber_num": "aaaaa", "insurance_order": 2 }, "patient": { "respparty": "self" } }, "account_code": "vclinic", "clinics": [ "vclinic" ], "created": 1649934637 } } |
Required Insurance Information
FirstName - first_name LastName - last_name DOB - dob Gender - gender Address - street_addr City - city State - state ZipCode - zip Relationship to Insured - insurance.respparty (e.g self, child, spouse, other) // Primary Insurance Fields Primary Insurance - insurance.primary_carrier_code (insurer_id) Primary Insurance Group Number - insurance.primary_group_number Primary Insurance Subscriber Number - insurance.primary_subscriber_num Primary Insurance Card Front - insurance.primary_card_front Primary Insurance Card Back - insurance.primary_card_back // Secondary Insurance Fields Secondary Insurance - insurance.secondary_carrier_code (insurer_id) Secondary Insurance Group Number - insurance.secondary_group_number Secondary Insurance Subscriber Number - insurance.secondary_subscriber_num Secondary Insurance Card Front - insurance.secondary_card_front Secondary Insurance Card Back - insurance.secondary_card_back If Relationship to Insured is 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/:carrier_code/eligibility
https://api-vclinic.vseepreview.com/vc/next/api_v3/users/:id/:carrier_code/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
VSee will create a patient record in AdvancedMD as needed if it’s not existing yet.
Result
Since the check may take up to 5 seconds to 1 minute, a webhook eligibility.checked
is triggered when it is ready.
Response
{ "data": { "eligibility_id": "2505465", "carrier_code": "car7556" } }
In case of error / missing data we should display a proper error message.
Raw Data in user_datas
It will populate the user’s primary insurance or secondary insurance eligibility response fields when response received from the 3rd party.
{ "data": { "id": "132407", "code": "edward+001.vclinic@vseelab.com", "first_name": "Edward", "last_name": "VSee", "full_name": "Edward VSee", "username": "edward+001.vclinic@vseelab.com", "vseeid": "ccpreview+6258012d656449b8b5e73ad964457b1f", "dob": "1986-01-01", "email": "edward+001.vclinic@vseelab.com", "gender": 1, "active": true, "tos": false, "status": 20, "subtype": "", "street_addr": "2868 Tully Street", "state": "Detroit", "city": "MI", "zip": "48226", "timezone": "America/Los_Angeles", "email_verified": true, "insurance": { "primary": { "carrier_code": "car7556", "subscriber_num": "234234", "insurance_order": 1, "insurance_coverage_id": "3708039", "eligibility_id": "2505465", "last_checked": 1649950742, "eligibility_response": "No response received by clearinghouse", "eligibility_text": "The payer response contains invalid or non compliant data.(70002)", "raw_response": { "?xml": { "@version": "1.0", "@encoding": "ISO-8859-1" }, "PPMDResults": { "@s": "PRDAPI1WFEYU1PO", "@lst": "4/14/2022 8:39:02 AM", "Results": { "@eligibilityid": "2505465", "@eligibilitystatusid": "1", "@eligibilitycreatedat": "04/14/2022 8:38AM", "@eligibilitychangedat": "04/14/2022 8:38AM", "@eligibilityresponsedate": "04/14/2022 8:38AM", "@patientname": "VSEE,EDWARD", "@address2": "2868 TULLY STREET", "@city": "MI", "@state": "DET", "@zipcode": "48226 ", "@dob": "1986-01-01T00:00:00", "@subscriberid": "234234", "@eligibilitystc": "30", "Edi271": { "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance", "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema", "InterchangeControlHeader": { "@ISA01_AuthorizationInformationQualifier": "00", "@ISA02_AuthorizationInformation": " ", "@ISA03_SecurityInformationQualifier": "00", "@ISA04_SecurityInformation": " ", "@ISA05_SenderInterchangeIdQualifier": "ZZ", "@ISA06_SendersInterchangeId": "MCKESSON_TSH ", "@ISA07_ReceiverInterchangeIdQualifier": "ZZ", "@ISA08_ReceiversInterchangeId": "007454 ", "@ISA09_Date": "220414", "@ISA10_Time": "1038", "@ISA11_InterchangeStandardsIdentifier": "|", "@ISA12_InterchangeVersionId": "00501", "@ISA13_InterchangeControlNumber": "000000001", "@ISA14_AcknowledgementRequested": "0", "@ISA15_TestIndicator": "P", "@ISA16_SubElementDelimeter": ":" }, "FunctionalGroupHeader": { "@GS01_FunctionalIdentifierCode": "HB", "@GS02_ApplicationSendersCode": "ZZDEMO", "@GS03_ApplicationReceiversCode": "025924AMD", "@GS04_Date": "20220414", "@GS05_Time": "103848", "@GS06_GroupControlNumber": "314159265", "@GS07_ResponsibleAgencyCode": "X", "@GS08_VersionIdentificationCode": "005010X279A1" }, "TransactionSets": { "TransactionSet": { "Header": { "STSegment": { "@ST01_TransactionSetIdentifierCode": "271", "@ST02_TransactionSetControlNumber": "000000001", "@ST03_ImplementationConventionReference": "005010X279A1" }, "BHTSegment": { "@BHT01_HierarchicalStructuralCode": "0022", "@BHT02_TransactionSetPurposeCode": "11", "@BHT03_ReferenceIdentification": "Prod9917412505465", "@BHT04_Date": "20220414", "@BHT05_Time": "103848" } }, "InformationSourceDetail": { "InformationSourceLevel": { "InformationSourceLevel": { "@HL01_HierarchicalIdNumber": "1", "@HL03_HierarchicalLevelCode": "20", "@HL04_HierarchicaChildCode": "1" } }, "InformationSourceName": { "InformationSourceName": { "@NM101_EntityIdentifierCode": "PR", "@NM102_EntityTypeQualifier": "2", "@NM103_LastOrOrganizationalName": "HEALTH CHOICE ARIZONA", "@NM108_IdentificationCodeQualifier": "PI", "@NM109_IdentificationCode": "ZZDEMO" }, "RequestValidations": { "AAASegment": { "@AAA01_ConditionOrResponseCode": "N", "@AAA03_RejectReasonCode": "80", "@AAA04_FollowUpActionCode": "R" } } } }, "InformationReceiverDetail": { "InformationReceiverLevel": { "ReceiverLevel": { "@HL01_HierarchicalIdNumber": "2", "@HL02_HierarchicalParentIdNumber": "1", "@HL03_HierarchicalLevelCode": "21", "@HL04_HierarchicaChildCode": "1" } }, "InformationReceiverName": { "ReceiverName": { "@NM101_EntityIdentifierCode": "1P", "@NM102_EntityTypeQualifier": "1", "@NM103_LastOrOrganizationalName": "JONES", "@NM104_FirstName": "CAMERON", "@NM108_IdentificationCodeQualifier": "XX", "@NM109_IdentificationCode": "2133321234" } } }, "SubscriberDetail": { "HierarchicalLevel": { "@HL01_HierarchicalIdNumber": "3", "@HL02_HierarchicalParentIdNumber": "2", "@HL03_HierarchicalLevelCode": "22", "@HL04_HierarchicaChildCode": "0" }, "Name": { "Name": { "@NM101_EntityIdentifierCode": "IL", "@NM102_EntityTypeQualifier": "1", "@NM103_LastOrOrganizationalName": "VSEE", "@NM104_FirstName": "EDWARD", "@NM108_IdentificationCodeQualifier": "MI", "@NM109_IdentificationCode": "234234" }, "EligibilityOrBenefitInformation": { "EligibilityOrBenefitInformation": { "EligibilityOrBenefitInformation": { "@EB01_EligibilityOrBenefitInformationCode": "V" }, "MessageTexts": { "MSGSegment": { "@MSG01_FreeFormMessageText": "The payer response contains invalid or non compliant data.(70002)" } } } } } } } }, "FunctionalGroupTrailer": { "@GE01_NumberOfTransactionSets": "1", "@GE02_GroupControlNumber": "314159265" }, "InterchangeControlTrailer": { "@IEA01_NumberOfFunctionalGroups": "1", "@IEA02_InterchangeControlReference": "000000001" } } } } } }, "secondary": { "carrier_code": "car11406", "group_number": "asdasd", "subscriber_num": "aaaaa", "insurance_order": 2 }, "patient": { "respparty": "self", "member_id": "5991794", "response_party_id": "6858376" } }, "account_code": "vclinic", "clinics": [ "vclinic" ], "created": 1649934637 } }
Webhook
{ "id": "62583ab3-8cfc-4a47-b6c9-272850e631f8", "type": "eligibility.checked", "created": 1649949363, "account_code": "vclinic", "data": { "eligibility_id": "2505464", "member_id": "132407", "eligibility_response": "No response received by clearinghouse", "external_member_id": "5991794" } }
Eligibility Responses List
eligibility_response
may be one of the following:
Success / Reject reason not found 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.
Rejection reason and codes
'04' => 'Authorized quantity exceeded', '15' => 'Required application data missing', '33' => 'Input Errors', '35' => 'Out of Network', '41' => 'Authorization/Access restrictions', '42' => 'Unable to respond at current time.', '43' => 'Invalid/Missing provider information', '44' => 'Invalid/Missing provider name', '45' => 'Invalid/Missing provider speciality', '46' => 'Invalid/Missing provider phone number', '47' => 'Invalid/Missing provider state', '48' => 'Invalid/Missing referring provider identification number', '49' => 'Provider is not primary care physician', '50' => 'Provider ineligible for inquiries', '51' => 'Provider not on file', '52' => 'Service dates not within provider plan enrollment', '53' => 'Inquired benefit inconsistent with provider type', '56' => 'Inappropriate date', '57' => 'Invalid/Missing dates of service', '58' => 'Invalid/Missing date of birth', '60' => 'Date of birth follows date of service', '61' => 'Date of death preceeds dates of service', '62' => 'Date of service not within allowable inquiry period', '63' => 'Date of service in future', '64' => 'Invalid/Missing patient ID', '65' => 'Invalid/Missing patient name', '66' => 'Invalid/Missing patient gender code', '67' => 'Patient not found', '69' => 'Inconsistent with patient age.', '70' => 'Inconsistent with patient gender.', '71' => 'Patient birth date does not match that for the patient in the database', '72' => 'Invalid/Missing subscriber/insured ID', '73' => 'Invalid/Missing subscriber/insured name', '74' => 'Invalid/Missing subscriber/insured gender code', '75' => 'Subscriber/Insured not found', '76' => 'Duplicate Subscriber/Insured ID number', '77' => 'Subscriber found, patient not found', '78' => 'Subscriber/Insured not in Group/Plan identified', '79' => 'Invalid participant identification', '97' => 'invalid or missing provider address', 'T4' => 'Payer name or identifier missing', 'T5' => 'Certification Information Missing', '80' => 'No response received by clearinghouse', '98' => 'Expiremental service or procedure.', 'AA' => 'Authorization number not found.', 'AE' => 'Requires primary care physician authorization.', 'AF' => 'Invalid/Missing diagnosis codes.', 'AG' => 'Invalid/Missing procedure codes.', 'AO' => 'Additional patient condition information required.', 'CI' => 'Certification information does not match patient.', 'E8' => 'Requires medical review.', 'IA' => 'Invalid authorization number format.', 'MA' => 'Missing authorization number.'
GET /insurances/
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.
Output
A list of supported insurers.
“id” here is AMD’s payer ID. “name” is readable name.
{ "data": { "insurers": [ { "id": "car7551", "name": "AETNA" }, { "id": "car7414", "name": "AETNA BETTER HEALTH OF ILLINOIS" }, { "id": "car11406", "name": "ANTHEM BLUE SHIELD" }, { "id": "car7147", "name": "CIGNA HEALTH CARE" }, { "id": "car7580", "name": "MONTGOMERY HEALTH INSURANCE" }, { "id": "car7556", "name": "HEALTH CHOICE ARIZONA" } ] } }
POST /insurance/claims
https://api-vclinic.vseepreview.com/vc/next/api_v3/insurance/claims
Claims collection
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 |
| … |
date_of_service | 12/1/2021 | |
location | 41 | |
procedure_code | U0003;U0005 | |
units | 1 | |
diagnosis_code | Z20.822;R05.9 |
Output
{ "data": { "id": "82828", } }
Webhook
{ "id": "5c34979c-30dc-496c-8cd3-6eb9925862c1", "type": "claims.updated", "visit_id": 1546950556, "account_code": "vclinic", "data": { "claim_id": "28540", "member_id": "60610", "status": "" } }