## Getting Started
### What is Eligibility Verification?
Eligibility Verification is one of the most important business processes in healthcare, ensuring patients' insurance coverage is confirmed before services are provided.
This process is crucial for smooth **provider reimbursement** and reducing billing surprises for patients, ultimately enhancing their **access to care**. It's a key step in delivering efficient, accessible healthcare services.
### What information does it provide?
* **Coverage Status**: Confirms whether the patient's insurance is currently active or inactive.
* **Benefit Details**: Outlines specific benefits covered under the patient's insurance plan, including types of services (e.g., outpatient, inpatient, laboratory services).
* **Deductible Information**: Details about the patient's deductible, including how much has been met and the remaining amount.
* **Co-pay Amounts**: Information on required co-pay amounts for different services (e.g., specialist visits, emergency room visits).
* **Co-insurance Rates**: Percentage of costs that the patient is responsible for after the deductible is met.
* **Out-of-Pocket Maximums**: The maximum amount the patient is required to pay out-of-pocket during a policy period.
* **Prior Authorization Requirements**: Indicates if certain services require prior authorization from the insurance provider.
* **Service Limitations**: Information on any limits to services, such as a cap on the number of visits or specific exclusions.
* **Network Status**: Confirmation of whether a provider or service is in-network or out-of-network, which affects the patient's costs.
### Prerequisites
Ready to get started? There are a few requirements to be able to use eligibility successfully.
* [x] Active CardScan.ai account with the eligibility feature enabled.
* [x] NPI of the provider or organization who will be providing the service.
* [x] Basic demographics for the **patient of interest.**
{% hint style="warning" %}
**Note:** Eligibility verification is a paid add-on feature. Please ensure that you have the appropriate subscription plan to access this functionality.
{% endhint %}
## Integration
### **UI Widgets**
For easy integration of the eligibility feature, developers can utilize our UI widgets. The React component and mobile SDKs provide straightforward methods to perform eligibility checks alongside the insurance card scanning process.
To trigger an eligibility request using our UI widgets, simply pass in the eligibility request payload as described below. The payload must include subscriber and dependent demographics, as well as provider details, including a National Provider Identifier (NPI). This information is crucial for accurately verifying insurance eligibility.
#### **Sample Request Payload:**
```json
{
"card_id": "c1b93738-ddc0-4beb-9936-1f93fe0e4279",
"eligibility": {
"subscriber": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "18020101"
},
"provider": {
"firstName": "Jane",
"lastName": "Doe",
"npi": "1952535221"
}
}
}
```
#### **Alternative Provider Format:**
```json
{
"card_id": "c1b93738-ddc0-4beb-9936-1f93fe0e4279",
"eligibility": {
"subscriber": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "18020101"
},
"provider": {
"organizationName": "STANFORD HEALTH CARE",
"npi": "1871543215"
}
}
}
```
You can locate a providers NPI on the [NPPES NPI Registry](https://npiregistry.cms.hhs.gov/search%23pageStart) search page.
{% hint style="info" %}
Date of birth is required to be in the\*\*`YYYYMMDD`\*\*format.
{% endhint %}
#### **Callbacks**
Our UI widgets provide two additional callbacks for handling eligibility verification results. Developers can implement `onEligibilitySuccess` and `onEligibilityError` to receive notifications when an eligibility check is successful or encounters an error, respectively.
#### **React Example:**
```jsx
import { CardScanView } from "@cardscan.ai/insurance-cardscan-react";
function EligibilityApp({ apiKey, ...props }) {
const eligibility = {
subscriber: {
firstName: "Joe",
lastName: "Doe",
dateOfBirth: "18020101",
},
provider: {
firstName: "John",
lastName: "Doe",
npi: "0123456789",
},
};
function cardScanSuccess(card) {
console.log(card);
}
function cardScanCancel() {
setShowScanView(false);
}
function cardScanError(error) {
console.log("Error Callback: ", error);
}
function eligibilitySuccess(eligibility) {
console.log(eligibility);
}
function eligibilityError(error) {
console.log(error);
}
return (
);
}
export default EligibilityApp;
```
### **API Integration**
For custom integrations, our Eligibility Verification Endpoints are designed to work in tandem with our Insurance Card Scanning Endpoints. By creating a new eligibility request, users can initiate an asynchronous process that verifies insurance coverage and benefits.
Please checkout the [#eligibility-verification](https://docs.cardscan.ai/api#eligibility-verification "mention") section of our API documentation for endpoint details and a **Postman** collection.
#### Sample Request Payload
To initiate an eligibility request through our API endpoints, two key pieces of information are required:
1. **Eligibility Request Payload:** This includes subscriber and dependent demographics, along with provider details, including a National Provider Identifier (NPI).
2. **Card ID:** The ID of a card in the `completed` state must also be provided to ensure the request is linked to the correct insurance card information.
{% hint style="info" %}
If you would like to use the API directly without first having scanned an insurance card, please reach out to support.
{% endhint %}
```json
{
"card_id": "cdeef0bd-f170-44fb-95a4-8d4dfb45bdfc",
"eligibility": {
"subscriber": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "18020101"
},
"provider": {
"firstName": "John",
"lastName": "Doe",
"npi": "0123456789"
}
}
}
```
You can locate a providers NPI on the [NPPES NPI Registry](https://npiregistry.cms.hhs.gov/search%23pageStart) search page.
{% hint style="info" %}
Date of birth is required to be in the\*\*`YYYYMMDD`\*\*format.
{% endhint %}
### Eligibility Response Formats
CardScan.ai provides eligibility data in **two formats** to serve different integration needs:
#### 1. **Normalized Response** (`eligibility_summarized_response`) - **Recommended**
Our clean, standardized format that normalizes data across all clearinghouses. This is what **90% of developers need** - consistent field names, standardized values, and easy-to-parse structure regardless of which clearinghouse processed the request.
#### 2. **Raw Clearinghouse Response** (`eligibility_response`) - **Advanced Use Cases**
The complete, unmodified response from the clearinghouse (Availity, Change Healthcare, etc.). Use this when you need access to clearinghouse-specific fields or want to implement your own parsing logic.
{% hint style="success" %}
**Recommendation:** Start with the `eligibility_summarized_response` for faster integration. The raw response is available when you need additional data not included in our normalized format.
{% endhint %}
{% hint style="info" %}
**Raw Response:** The complete clearinghouse response contains extensive additional data including detailed benefits, service-specific coverage, and clearinghouse-specific fields that may be useful for advanced integrations.
{% endhint %}
```json
{
"subscriber_details": {
"member_id": "27312103",
"firstname": "Joshua",
"lastname": "Marshall",
"middlename": "Jennifer",
"gender": "M",
"address": {
"address1": "391 John Spur Apt. 163",
"city": "Lake Garrett",
"state": "MD",
"postalCode": "26540"
},
"dob": "2006-05-17"
},
"payer_details": {
"payer_name": "Aetna",
"address": {
"address1": "PO Box 14079",
"city": "Lexington",
"state": "KY",
"postalCode": "40512"
}
},
"plan_details": {
"plan_number": "2675107",
"group_name": "Harris Ltd",
"group_number": "137409668",
"plan_start_date": "2022-12-01",
"plan_eligibility_start_date": "2022-01-01",
"plan_name": "Open Access Elect Choice",
"plan_active": true
},
"coverage_summary": {
"individual_deductible_in_network": {
"total_amount": "$3500",
"remaining_amount": "$2533.86"
},
"individual_oop_in_network": {
"total_amount": "$6350",
"remaining_amount": "$5383.86"
},
"family_deductible_in_network": {
"total_amount": "$7000",
"remaining_amount": "$5040.17"
},
"family_oop_in_network": {
"total_amount": "$12700",
"remaining_amount": "$10740.17"
}
},
"chiropractic": {
"co_insurance_in_network": {
"amount": "20%"
},
"co_payment_in_network": {
"amount": "$0"
},
"service_code": "33"
},
"emergency_room": {
"co_insurance_in_network": {
"amount": "20%"
},
"co_payment_in_network": {
"amount": "$0"
},
"service_code": "86"
},
"office_visit": {
"co_insurance_in_network": {
"amount": "20%"
},
"co_payment_in_network": {
"amount": "$0"
},
"service_code": "98"
},
"urgent_care": {
"co_insurance_in_network": {
"amount": "20%"
},
"co_payment_in_network": {
"amount": "$0"
},
"service_code": "UC"
},
"hospital_outpatient": {
"co_insurance_in_network": {
"amount": "20%"
},
"co_payment_in_network": {
"amount": "$0"
},
"service_code": "50"
}
}
```
### Testing
To facilitate easier testing, our sandbox environment is configured to trigger specific errors based on certain input values:
* **Invalid NPI Error:** Use a provider NPI value of `12345678` to simulate an "Invalid NPI" error.
* **Mismatched DOB Error:** Use a subscriber date of birth (DOB) value of `19020402` to simulate a "Mismatched DOB" error.
* **Name Misspelled Error:** Use a subscriber first name of `Walt` and last name of `Witman` to simulate a "Name Misspelled" error.
## **Troubleshooting and Support**
Encountering issues while using the Eligibility Verification feature is not uncommon. Below are some common errors you might face, along with guidance on how to resolve them:
**InvalidNPIException**
* **Cause**: This exception occurs when the NPI (National Provider Identifier) provided is either incorrect, not found in the NPI database, or not registered with the payer.
* **Resolution**: Double-check the NPI number for accuracy. Ensure that it is correctly registered in the NPI database. You can verify NPI numbers using the [official NPI Registry.](https://npiregistry.cms.hhs.gov/)
**MismatchedDOBException**
* **Cause**: This exception is triggered when the patient's Date of Birth (DOB) does not match the records or is formatted incorrectly.
* **Resolution**: Verify that the patient's DOB is correct and formatted in the YYYYMMDD format. Cross-reference with patient records for accuracy.
**NameMisspelledException**
* **Cause**: A common issue where the patient's name might be misspelled or entered incorrectly.
* **Resolution**: Check for any common misspellings, swapping of first/last names, or typographical errors in the patient's name. Correct the name and try again.
**General Tips**
* **API Response Timeouts**: If you encounter timeouts, check your network connection and server status. If the issue persists, contact our support team.
* **Data Format Errors**: Ensure all data sent in API requests adhere to the specified format guidelines in our documentation.
### **Support Contact**
If you continue to experience issues or have specific queries, our support team is here to help:
* **Email Support**: Reach out to us at with detailed information about your issue.
