Insurance API

Owned by Anton Tolkachiov
Last updated: May 15, 2024 by An Nguyen
14 min read

Create / update delete / retrieve insurance detail

Sample insurance schema:

"insurance": [ { "name": "Insurance", "code": "insurance", "card_type": "primary", "next": { "title": "Next" }, "sections": [ { "code": "insurance", "default_value": [ "carrier_code", "subscriber_num", "group_number" ], "prefill_mapping": { "respparty": { "self": { "guarantor_name": "full_name", "guarantor_dob": "dob", "guarantor_address": "street_addr", "guarantor_city": "city", "guarantor_zip": "zip", "guarantor_state": "state" } } }, "schema": { "has_ins": { "type": "string", "title": "", "required": true, "enum": [ "Yes", "No" ], "default": "No" }, "carrier_code": { "type": "string", "title": "Primary Insurance Company Name", "required": true, "prefill": { "user_attr": "insurance.primary.carrier_code" }, "preload": { "url": "https://api-vclinic.vsee.me/claims_v2/api_v3/insurances/list/insurers", "format": { "data": { "id": "id", "text": "text" } } } }, "carrier_name_others": { "type": "string", "title": "Other Insurance", "required": true, "prefill": { "user_attr": "insurance.primary.carrier_name_others" } }, "subscriber_num": { "type": "string", "title": "Policy Number / Subscriber ID", "required": true, "prefill": { "user_attr": "insurance.primary.subscriber_num" } }, "group_number": { "type": "string", "title": "Group Number", "prefill": { "user_attr": "insurance.patient.group_number" } }, "respparty": { "type": "string", "title": "Patient Relationship to Policy Holder", "required": true, "enum": [ "", "self", "child", "spouse", "other" ], "prefill": { "user_attr": "insurance.patient.respparty" } }, "guarantor_first_name": { "type": "string", "title": "Insured First Name", "required": true, "prefill": { "user_attr": "first_name", "only": "self" } }, "guarantor_last_name": { "type": "string", "title": "Insured Last Name", "required": true, "prefill": { "user_attr": "last_name", "only": "self" } }, "guarantor_middle_name": { "type": "string", "title": "Insured Middle Name", "prefill": { "user_attr": "extra.middle_name", "only": "self" }, "required": false }, "guarantor_dob": { "type": "string", "title": "Insured Date of Birth", "required": true, "format": "yyyy-mm-dd", "prefill": { "user_attr": "dob", "only": "self" } }, "guarantor_address": { "type": "string", "title": "Insured Address", "required": true, "prefill": { "user_attr": "street_addr" } }, "guarantor_city": { "type": "string", "title": "Insured City", "required": true, "prefill": { "user_attr": "city" } }, "guarantor_zip": { "type": "string", "title": "Insured Zip", "required": true, "prefill": { "user_attr": "zip" } }, "guarantor_state": { "type": "string", "title": "Insured State", "required": true, "enum": [ "", "AK", "AL", "AR", "AZ", "CA", "CO", "CT", "DC", "DE", "FL", "GA", "HI", "IA", "ID", "IL", "IN", "KS", "KY", "LA", "MA", "MD", "ME", "MI", "MN", "MO", "MS", "MT", "NC", "ND", "NE", "NH", "NJ", "NM", "NV", "NY", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VA", "VT", "WA", "WI", "WV", "WY" ], "prefill": { "user_attr": "state" } }, "card_front": { "type": "string", "title": "Upload Insurance Card (Front)", "required": true, "prefill": { "user_attr": "insurance.primary.card_front" } }, "card_back": { "type": "string", "title": "Upload Insurance Card (Back)", "required": true, "prefill": { "user_attr": "insurance.primary.card_back" } }, "consent": { "type": "string", "required": true, "title": "I give the <a href='#'>authorization to bill insurance</a>" } }, "form": [ { "type": "help", "helpvalue": "We wish to offer clarity on how Company bills you/your insurance for services you received, please read the following before making a payment selection.<br /><br />Although we do accept your insurance information as a method to facilitate payment for the Company, We do not know (in real-time) details about your co-payment, deductible, or out-of-pocket expenses, which may affect insurance coverage and compensation for billed services. Our billed rates are based on coding rates set by our contract with your insurance. They range between $150-$350 (depending on codes and visit type). These rates, however, are not the same as our discounted cash visit rates. If you have insurance with high deductibles or out-of-pocket expenses, your insurance company may choose to apply the entire billed amount towards your deductible, and you will be responsible for the full billed amount in the future.<br /><br />For parents with high deductibles, out of pocket expenses or those who wish to avoid higher payments beyond the insurance billing option, we offer a discounted cash payment option. Our cash prices per visit are extremely competitive compared to current market rates of private providers or consultants, and they are discounted by 60% from our billable rates.<br /><br />Once we bill your insurance, we are unable to revert back to cash payment rates, and by law, we are required to collect the full amount applied toward your deductible or co-pay from you.<br /><br />" }, { "key": "has_ins", "type": "radios", "notitle": true, "titleMap": { "Yes": "I would like to use my insurance", "No": "I would like to pay upfront for this visit (cash payment)" }, "toggleMap": { "Yes": { "form": [ { "type": "help", "helpvalue": "<i style='color: red'>If you choose OTHER, you are required to upload the front and back pictures of your insurance card.</i>" }, { "key": "carrier_code", "placeholder": "Type first 3 letters to search", "type": "select2", "titleMap": { "car7551": "AETNA" }, "htmlClass": "col-md-6 col-xs-6 col-sm-12", "toggleMap": { "OTHER": { "form": [ { "key": "carrier_name_others", "placeholder": "Other Insurance", "type": "text" } ], "htmlClass": "col-md-6 col-xs-6 col-sm-12" } } }, { "key": "subscriber_num", "placeholder": "Enter Policy Number / Subscriber ID*", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "group_number", "placeholder": "Enter Group Number", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "respparty", "placeholder": "Select relationship", "titleMap": { "self": "Self", "child": "Child", "spouse": "Spouse", "other": "Others" }, "type": "select", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_first_name", "placeholder": "Enter Insured First Name*", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_last_name", "placeholder": "Enter Insured Last Name*", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_middle_name", "placeholder": "Enter Insured Middle Name", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_dob", "type": "datepicker", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_address", "placeholder": "Enter address", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_city", "placeholder": "Enter city", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_zip", "placeholder": "Enter Zip", "type": "text", "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "guarantor_state", "type": "select", "titleMap": { "AL": "Alabama", "AK": "Alaska", "AZ": "Arizona", "AR": "Arkansas", "CA": "California", "CO": "Colorado", "CT": "Connecticut", "DE": "Delaware", "DC": "District of Columbia", "FL": "Florida", "GA": "Georgia", "HI": "Hawaii", "ID": "Idaho", "IL": "Illinois", "IN": "Indiana", "IA": "Iowa", "KS": "Kansas", "KY": "Kentucky", "LA": "Louisiana", "ME": "Maine", "MD": "Maryland", "MA": "Massachusetts", "MI": "Michigan", "MN": "Minnesota", "MS": "Mississippi", "MO": "Missouri", "MT": "Montana", "NE": "Nebraska", "NV": "Nevada", "NH": "New Hampshire", "NJ": "New Jersey", "NM": "New Mexico", "NY": "New York", "NC": "North Carolina", "ND": "North Dakota", "OH": "Ohio", "OK": "Oklahoma", "OR": "Oregon", "PA": "Pennsylvania", "RI": "Rhode Island", "SC": "South Carolina", "SD": "South Dakota", "TN": "Tennessee", "TX": "Texas", "UT": "Utah", "VT": "Vermont", "VA": "Virginia", "WA": "Washington", "WV": "West Virginia", "WI": "Wisconsin", "WY": "Wyoming" }, "htmlClass": "col-md-6 col-xs-6 col-sm-12" }, { "key": "card_front", "title": "Upload Insurance Card (Front)", "type": "attachments", "id": "cardFrontArea", "height": "100px", "single": true, "htmlClass": "col-md-12 col-xs-12 col-sm-12" }, { "key": "card_back", "title": "Upload Insurance Card (Back)", "type": "attachments", "id": "cardBackArea", "height": "100px", "single": true, "htmlClass": "col-md-12 col-xs-12 col-sm-12" }, { "key": "consent", "htmlClass": "col-md-12 col-xs-12 col-sm-12", "type": "checkbox", "notitle": true, "inlinetitle": "I give the <a target='_blank' href='https://api-vclinic.vsee.me/files/view/65f07a66-59b4-4b00-a111-05c10adc645d'>authorization to bill insurance</a>" }, { "type": "label", "label": "Your insurance will be verified but we still need your credit card information in case of deductible or co payment requirements in the next screen." } ] } } } ] } ] }, { name: "Insurance", card_type: "secondary", schema: {}, form: {} } ]

GET api_v3/users/{user_id}/insurances

{ "data": [ { "consent": false, "group_number": "sdf", "subscriber_number": "ad", "card_front": { "id": "6552fbe8-d848-491f-8310-08de0a7d6499", "fullpath": "https://api-vclinic.vsee.me/files/view/6552fbe8-d848-491f-8310-08de0a7d6499?auth_code=1b41e14a509dc23ec0a496c65583fff972541a77&time=1699944950", "is_deletable": false }, "card_back": { "id": "6552fbec-4994-4743-8328-0e380a7d6499", "fullpath": "https://api-vclinic.vsee.me/files/view/6552fbec-4994-4743-8328-0e380a7d6499?auth_code=1b41e14a509dc23ec0a496c65583fff972541a77&time=1699944950", "is_deletable": false }, "guarantor_name": "as", "guarantor_dob": "2023-11-06", "guarantor_address": "as", "guarantor_city": "as", "guarantor_state": "AR", "guarantor_zip": "as", "card_type": "primary", "eligibility": { "status": "inactive" }, "insurer_code": "car7777", "insurer_name": "ANTHEM BLUE CROSS", "responsible_party": "child" }, { "consent": false, "group_number": "sdf", "subscriber_number": "ad", "card_front": { "id": "6552fbe8-d848-491f-8310-08de0a7d6499", "fullpath": "https://api-vclinic.vsee.me/files/view/6552fbe8-d848-491f-8310-08de0a7d6499?auth_code=1b41e14a509dc23ec0a496c65583fff972541a77&time=1699944950", "is_deletable": false }, "card_back": { "id": "6552fbec-4994-4743-8328-0e380a7d6499", "fullpath": "https://api-vclinic.vsee.me/files/view/6552fbec-4994-4743-8328-0e380a7d6499?auth_code=1b41e14a509dc23ec0a496c65583fff972541a77&time=1699944950", "is_deletable": false }, "guarantor_name": "as", "guarantor_dob": "2023-11-06", "guarantor_address": "as", "guarantor_city": "as", "guarantor_state": "AR", "guarantor_zip": "as", "card_type": "secondary", "eligibility": { "status": "inactive" }, "insurer_code": "car7777", "insurer_name": "ANTHEM BLUE CROSS", "responsible_party": "child" } ], "version": "2.0" }

POST api_v3/users/{user_id}/insurances/import

  • Post in array

  • If there is primary existed, update else insert

{ "insurances": [ { "consent": false, "group_number": "sdf", "subscriber_number": "ad", "card_front": "6552fbe8-d848-491f-8310-08de0a7d6499", "card_back": "6552fbec-4994-4743-8328-0e380a7d6499", "guarantor_name": "as", "guarantor_dob": "2023-11-06", "guarantor_address": "as", "guarantor_city": "as", "guarantor_state": "AR", "guarantor_zip": "as", "insurer_code": "car7777", "insurer_name": "ANTHEM BLUE CROSS", "responsible_party": "child" }, { "consent": false, "group_number": "sdf", "subscriber_number": "ad", "card_front": "6552fbe8-d848-491f-8310-08de0a7d6499", "card_back": "6552fbec-4994-4743-8328-0e380a7d6499", "guarantor_name": "as", "guarantor_dob": "2023-11-06", "guarantor_address": "as", "guarantor_city": "as", "guarantor_state": "AR", "guarantor_zip": "as", "insurer_code": "car7777", "insurer_name": "ANTHEM BLUE CROSS", "responsible_party": "child" } ] }

POST api_v3/users/{user_id}/insurances/{card_type|primary|secondary}

If the insurance schema doesn’t have card_type, we should set it as primary as default. ( @Duong Dang )

GET api_v3/users/{user_id}/insurances/{card_type|primary|secondary}

DELETE api_v3/users/{user_id}/insurances/{card_type}

Eligibility check

POST api_v3/users/{user_id}/insurances/primary/eligibility/check

  • Check and return queue status and current eligibility status

  • Known issue: every post will submit new check (to optimize later)

GET api_v3/users/{user_id}/insurances/primary/eligibility

  • Return queue status and current eligibility status