Eligibility
ZapEHR provides a realtime insurance eligibility check endpoint. Submit a patient's insurance information and receive a response detailing the patient's coverage and benefits information.
Making an Eligibility Check Request
You can perform an eligibility check with either the Typescript SDK or the API:
Perform an eligibility check with the SDK:
zapehr.project.rcm.eligibilityCheck({
payerId: '00001',
provider: {
organizationName: 'happy doctors group',
npi: '0123456789',
},
subscriber: {
firstName: 'johnone',
lastName: 'doeone',
dateOfBirth: '1880-01-02',
memberId: '0000000000',
},
testMode: true
})
payerId
— Look up the payer ID for the insurance held by the patient here (opens in a new tab).provider.npi
— The NPI of the practice submitting the eligibility check.subscriber.memberId
— The member ID from the patient's insurance card.
The response body includes the complete CoverageEligibilityResponse resource detailed below.
Test Mode
While you are building your workflow around the Eligibility Check endpoint, you can include an additional flag in your request to enable "test mode". When test mode is enabled, your requests will not be sent to the payer. Instead, ZapEHR will return a sample response you can use to learn how various payer responses look, and test your workflow.
In test mode, you get a different response depending on the payerId
value in the input. Use the values in the following table in order to test different scenarios:
Test Mode — payerId / response mapping
payerId | Response Details |
---|---|
00001 | This is a canned response that returns a single coverage plan. This will work for any payer. |
000002 | This is a canned response that returns a badly formatted 271. This will work for any payer. |
00003 | This is a canned response that returns a good 271 that contains maxed MSG01 field (AN..264) and EB03 repeating data element (99 repeats). This will work for any payer. |
00004 | This is a canned response that returns AAA Not Eligible For Inquiries. This will work for any payer. |
00005 | This is a canned response that contains non-printable characters which we need to make sure we can parse. This will work for any payer. |
00006 | A system error from the Payer. AAA segment in the 2000A Information Source Loop with AAA01 = Y, AAA03 = 42 and AAA04 = R. |
00007 | This is a canned response that returns a single coverage plan with unused fields. This will work for any payer. |
000008 | This is a canned response that returns a 271 that contains data in deprecated fields. It is used to test our parser's handling of data in these fields. This will work for any payer. |
00009 | This returns a canned 271 response where the patient is a dependent. |
000010 | Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Date of Service and service type as input parameters. |
000011 | Rehabilitation Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Last Name Date of Service and service type as input parameters. |
000012 | Medical Care Inquiry: A 270 request with provider ID, subscriber ID, Date of Service and service type as input parameters. |
000013 | Rehabilitation Inquiry: A 270 request with provider ID, Subscriber last name, first name, Date of Service and service type as input parameters. Sample response from Health Maintenance Organization (HMO) Blue. |
000014 | Vision (Optometry) Inquiry: A 270 request with provider ID, subscriber ID, SSN, DOB, Date of Service and service type as input parameters. |
000015 | Home Health Care Inquiry: A 270 request with provider ID, subscriber ID, DOB, Date of Service and service type as input parameters. |
000016 | Pharmacy Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Last Name, Date of Service and service type as input parameters. |
000017 | Medical Care Inquiry: A 270 request with provider ID, subscriber ID, Date of Service and service type as input parameters. |
000018 | Emergency Services Inquiry: A 270 request with Information Receiver, Subscriber ID, Subscriber Last Name, Date of Service and Service Type parameters as follows is given as input. |
000019 | Rehabilitation Inquiry: A 270 request with provider ID, subscriber SSN, DOB, Date of Service and service type as input parameters. |
000020 | Rehabilitation Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Date of Service and service type as input parameters. |
000021 | Rehabilitation Inquiry: A 270 request with provider ID, DOB, First Name, Last Name Date of Service and service type as input parameters. |
000022 | Medical Care Inquiry: A 270 request with provider ID, subscriber ID, Date of Service and service type as input parameters. |
000023 | Health Benefit Plan Coverage Inquiry: A 270 request with provider ID, subscriber ID, Last Name, First Name, Date of Service and service type as input parameters. Sample response from Medicare Part A/Medicare Part B. |
000024 | Health Benefit Plan Coverage Inquiry: A 270 request with provider ID, subscriber ID, First Name, Date of Service and service type as input parameters. |
000025 | Rehabilitation Inquiry: A 270 request with provider ID, subscriber ID, Last Name, Date of Service and service type as input parameters. |
000026 | Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, service type and diagnosis code as input parameters. |
000027 | Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, service type and provider code as input parameters. |
000028 | Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, service type and provider information as input parameters. |
000029 | Health Benefit Plan Coverage Inquiry: A 270 request with Invalid Provider ID. |
000030 | Health Benefit Plan Coverage Inquiry: A 270 request with Invalid Patient Information. |
000031 | Health Benefit Plan Coverage Inquiry: A 270 request with Inactive Coverage date as service date. |
000032 | Health Benefit Plan Coverage Inquiry: A 270 request with Duplicate. Subscriber ID. |
000033 | Health Benefit Plan Coverage Inquiry: A 270 request with Invalid Provider ID. |
000034 | Rehabilitation Inquiry: A 270 request with Subscriber ID, Dependent first Name and service type code as input parameters. |
000035 | Pharmacy Inquiry: A 270 request with Subscriber ID, Dependent first Name and service type as input parameters. |
00036 | Florida Medicaid: Sample response. |
000036 | Home Health Care Inquiry: A 270 request with Subscriber ID, Dependent DOB and service type as input parameters. |
000037 | Psychiatric Inquiry: A 270 request with Subscriber ID, Dependent First Name and service type as input parameters. |
000038 | Rehabilitation Inquiry: A 270 request with Subscriber ID, Dependent DOB, Dependent Last Name and service type as input parameters. |
000039 | Different Deductible at 30 and other STC. |
000040 | EB 1 with no benefits (Active Coverage) and EB I (Non Covered). |
000041 | Test EB 6 (Inactive) and EB W (Other Source of Data). |
000042 | EB R — other additional payer. Sample use case for standard Medicaid benefit. |
000043 | EB W response (Other source of Data). |
000044 | High Out of pocket remaining but no deductible in response. |
000045 | Low Deductible High Premium — many different copayments. |
000046 | Low Deductible High Premium with no coinsurance. |
000047 | Low Deductible High Premium. |
000048 | Low Deductible with no copayment. |
000049 | Multiple Services. |
000050 | No Deductible, High Out of Pocket Remaining, only Copay and coinsurance. |
000051 | No Deductible, only copay for 33,98, UC. |
000052 | No Deductible, No copayment. |
000053 | Plan with active coverage but no patient responsibility. |
000054 | Response with AD time period 25. |
000055 | Too many deductibles at service levels. |
000056 | Uniquely formatted EB segment. |
000067 | Sample use case from PAA. |
000068 | Sample use case 2 from PAA. |
000069 | Sample Use case for EB V (Cannot Process). |
000070 | Sample Use case for EB U (Contact Following Entity for Eligibility or Benefit Information). |
000074 | Sample Use case for Connecticut Medicaid. |
000081 | Sample response for WellCare. |
000082 | Sample response for Blue Cross Blue Shield Georgia. |
000083 | Sample response for Humana. |
ABHFL | Sample use case for Aetna Better Health of Florida. |
ABHKY | Sample use case for Aetna Better Health of Kentucky. |
ABHLA | Sample use case for Aetna Better Health of Louisiana. |
ABHMO | Sample use case for Aetna Better Health of Missouri. |
AETNX | Sample response for AETNA. |
BCCTC | Sample use case for Blue Cross Blue Shield Connecticut. |
BCNJC | Sample response for BCBS of New Jersey (Horizon). |
CABC | A 270 request with memberId, firstName, lastName,gender,entityIdentifier,entityType,dateOfBirth,groupNumber,relationToSubscriber, insuredIndicator,maintenanceTypeCode, and maintenanceReasonCode. Sample response for Platinum Full PPO 250 15 OFFEX. |
CIGNA | A sample response for CIGNA for dependent. |
CMSMED | A 270 request with additional fields. Sample response for Medicare Part A/Medicare Part B. |
CNTCR | Sample use case for Connecticare Inc. |
COVON | Sample response for Coventry. |
CT | Sample use case for Connecticut Medicaid. |
DENTAL | Sample response for benefits from Dental Payer. |
HUM | Sample response for Humana. |
ILMSA | Sample use case for Aetna Better Health of Illinois. |
ISCAM | Sample response for Medi-CAL Portal connection. |
MA/MB | Sample response for Medicare Part A/Medicare Part B. |
MEDX | Sample response for MEDEX. |
MMSI | Sample use case for Mayo. |
TRICE | Sample response for Tricare. |
TX | Sample response for Texas Medicaid. |
TXBCBS | Sample response for Blue Advantage HMO. |
UHC | Sample response for United Healthcare. |
When using test mode, you must use these specific values for the provider and subscriber in the input body:
{
"provider": {
"organizationName": "happy doctors group",
"npi": "0123456789"
},
"subscriber": {
"firstName": "johnone",
"lastName": "doeone",
"dateOfBirth": "1880-01-02",
"memberId": "0000000000"
}
}
Although these values are required, only the payerId
value is used to determine the response you will receive.
Eligibility on FHIR
The insurance eligibility check endpoint is integrated directly with the FHIR service. When you submit an eligibility check request, ZapEHR creates two FHIR resources automatically: CoverageEligibilityRequest, and CoverageEligibilityResponse. These resources are created in Project's FHIR store and can be accessed using FHIR search.
CoverageEligibilityRequest
This resource is automatically created to document the requested eligibility check.
Sample Resource
This sample CoverageEligibilityRequest was created by the eligibility check endpoint:
{
"resourceType": "CoverageEligibilityRequest",
"identifier": [
{
"system": "https://terminology.zapehr.com/rcm-control-number",
"value": "000000002"
}
],
"status": "active",
"purpose": ["validation"],
"patient": {
"reference": "#patient"
},
"created": "2023-12-07T02:37:56.042Z",
"insurer": {
"reference": "#insurer"
},
"insurance": [
{
"coverage": {
"reference": "#coverage"
}
}
],
"extension": [
{
"url": "https://terminology.zapehr.com/rcm-payer-id",
"valueString": "00001"
}
],
"contained": [
{
"resourceType": "Patient",
"id": "patient",
"name": [
{
"given": ["johnone"],
"family": "doeone"
}
],
"birthDate": "1880-01-02"
},
{
"resourceType": "Organization",
"id": "insurer",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1760854442"
}
],
"name": "happy doctors group"
},
{
"resourceType": "Coverage",
"id": "coverage",
"status": "active",
"subscriber": {
"reference": "#patient"
},
"subscriberId": "0000000000",
"beneficiary": {
"reference": "#patient"
},
"payor": [
{
"reference": "#insurer"
}
]
}
],
"id": "064cd276-9423-40ef-b775-728372829c87",
"meta": {
"versionId": "7b61c393-af85-4648-9c4a-af0671010fbf",
"lastUpdated": "2023-12-07T02:37:59.828Z"
}
}
CoverageEligibilityResponse
This resource is automatically created to document the response received from the insurance payer.
Benefits
The key information used to understand whether a Patient has active coverage of the appropriate type for the services you're providing is found in CoverageEligibilityResponse.insurance.item (opens in a new tab). This property holds an array of benefits provided by the payer. These benefits are coded following the X12 service type codes (opens in a new tab) standard.
Examples of CoverageEligibilityResponse.insurance.item (opens in a new tab):
These two examples show a benefit with a service type code of 30
. This code is defined in the coding standard (opens in a new tab) as:
Plan coverage and general benefits for the member's policy or contract.
For many use cases, 30
is the only code you are looking for to determine whether the patient is covered for your services. From the above examples, you can determine that the patient has active coverage and a maximum out of pocket of $4195.37.
Active Coverage
{
"name": "Active Coverage",
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"unit": {
"coding": [
{
"code": "IND",
"display": "Individual",
},
],
},
"benefit": [
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "30"
}
]
}
}
]
}
Out of Pocket Maximum
{
"name": "Out of Pocket (Stop Loss)",
"network": {
"coding": [
{
"code": "Y",
"display": "Yes"
}
]
},
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"unit": {
"coding": [
{
"code": "IND",
"display": "Individual"
}
]
},
"term": {
"coding": [
{
"code": "29",
"display": "Remaining"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"code": "G",
"display": "Out of Pocket (Stop Loss)"
}
]
},
"allowedString": "4195.37"
},
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "30"
}
]
}
}
]
}
These two examples show a benefit with a service type code of 98
. This code is defined in the coding standard (opens in a new tab) as:
Prescription Drug
These benefits describe the copayment and coinsurance for prescription drugs. The allowedString
property holds the amount of the copayment of $30 and a 0.3% coinsurance.
Copayment
{
"name": "Co-Payment",
"network": {
"coding": [
{
"code": "Y",
"display": "Yes"
}
]
},
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"unit": {
"coding": [
{
"code": "IND",
"display": "Individual"
}
]
},
"term": {
"coding": [
{
"code": "27",
"display": "Visit"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"code": "B",
"display": "Co-Payment"
}
]
},
"allowedString": "30"
},
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "98"
}
]
}
}
]
}
Coinsurance
{
"name": "Co-Insurance",
"network": {
"coding": [
{
"code": "Y",
"display": "Yes"
}
]
},
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"unit": {
"coding": [
{
"code": "IND",
"display": "Individual"
}
]
},
"term": {
"coding": [
{
"code": "27",
"display": "Visit"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"code": "A",
"display": "Co-Insurance"
}
]
},
"allowedString": ".3%"
},
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "98"
}
]
}
}
]
}
Contained Resources
ZapEHR completes the CoverageEligibilityResponse resource using Contained Resources (opens in a new tab) for the following reference properties:
- CoverageEligibilityResponse.patient (opens in a new tab)
- CoverageEligibilityResponse.insurer (opens in a new tab)
- CoverageEligibilityResponse.insurance.coverage (opens in a new tab)
Inside the resource, you will find a property called contained
that holds these Contained Resources. You may want to lift some or all of these Contained Resources out of the CoverageEligibilityResponse and store them as typical resources in your FHIR store. You would just call FHIR create for each resource you wanted to make as a standalone resource.
Complete Response Extension
ZapEHR also includes the complete eligibility check response from the payer in the https://terminology.zapehr.com/change-api-response
extension. In the event that the eligibility check response has some data in it that ZapEHR is not automatically mapping into FHIR resources, having the complete response in the extension allows you to parse the response and create your own FHIR resources.
Sample Resource
This sample CoverageEligibilityResponse was created by the eligibility check endpoint:
{
"resourceType": "CoverageEligibilityResponse",
"identifier": [
{
"system": "https://terminology.zapehr.com/rcm-control-number",
"value": "000000002"
}
],
"status": "active",
"purpose": ["validation"],
"patient": {
"reference": "#patient"
},
"created": "2023-12-07T02:38:01.391Z",
"request": {
"reference": "CoverageEligibilityRequest/064cd276-9423-40ef-b775-728372829c87"
},
"outcome": "complete",
"insurer": {
"reference": "#insurer"
},
"insurance": [
{
"coverage": {
"reference": "#coverage"
},
"item": [
{
"name": "Active Coverage",
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "30"
}
]
}
}
]
},
{
"name": "Active Coverage",
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "88"
}
]
}
}
]
},
{
"name": "Active Coverage",
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "90"
}
]
}
}
]
},
{
"name": "Active Coverage",
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "89"
}
]
}
}
]
},
{
"name": "Active Coverage",
"category": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/ex-benefitcategory",
"code": "1",
"display": "Medical Care"
}
]
},
"benefit": [
{
"type": {
"coding": [
{
"system": "https://x12.org/codes/service-type-codes",
"code": "54"
}
]
}
}
]
}
]
}
],
"contained": [
{
"resourceType": "Patient",
"id": "patient",
"name": [
{
"given": ["johnone"],
"family": "doeone"
}
],
"birthDate": "1880-01-02"
},
{
"resourceType": "Organization",
"id": "insurer",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1760854442"
}
],
"name": "happy doctors group"
},
{
"resourceType": "Coverage",
"id": "coverage",
"status": "active",
"subscriber": {
"reference": "#patient"
},
"subscriberId": "0000000000",
"beneficiary": {
"reference": "#patient"
},
"payor": [
{
"reference": "#insurer"
}
]
}
],
"extension": [
{
"url": "https://terminology.zapehr.com/change-api-response",
"valueString": "{\"meta\":{\"senderId\":\"APIM_Marketplace_Native_51375219\",\"applicationMode\":\"sandbox\",\"traceId\":\"9d74be8a-f1e7-9cb0-3052-905d9db09298\"},\"controlNumber\":\"000000002\",\"reassociationKey\":\"000000002\",\"tradingPartnerServiceId\":\"00001\",\"provider\":{\"providerName\":\"happy doctors group\",\"entityIdentifier\":\"Provider\",\"entityType\":\"Non-Person Entity\",\"npi\":\"1760854442\"},\"subscriber\":{\"healthCareDiagnosisCodes\":[{\"diagnosisTypeCode\":\"BK\",\"diagnosisCode\":\"8901\"},{\"diagnosisTypeCode\":\"BF\",\"diagnosisCode\":\"87200\"},{\"diagnosisTypeCode\":\"BF\",\"diagnosisCode\":\"5559\"}],\"memberId\":\"0000000000\",\"firstName\":\"johnone\",\"lastName\":\"doeone\",\"entityIdentifier\":\"Insured or Subscriber\",\"entityType\":\"Person\",\"dateOfBirth\":\"18800102\",\"relationToSubscriber\":\"Self\",\"insuredIndicator\":\"Y\",\"maintenanceTypeCode\":\"001\",\"maintenanceReasonCode\":\"25\",\"birthSequenceNumber\":\"1\"},\"subscriberTraceNumbers\":[{\"traceTypeCode\":\"1\",\"traceType\":\"Current Transaction Trace Numbers\",\"referenceIdentification\":\"000000002\",\"originatingCompanyIdentifier\":\"9EMDEON999\"}],\"payer\":{\"entityIdentifier\":\"Payer\",\"entityType\":\"Non-Person Entity\",\"name\":\"Unknown\",\"payorIdentification\":\"00001\"},\"planInformation\":{\"policyNumber\":\"0000000000\"},\"planDateInformation\":{\"plan\":\"20131015\"},\"planStatus\":[{\"statusCode\":\"1\",\"status\":\"Active Coverage\",\"planDetails\":\"BEDROCK PLAN\",\"serviceTypeCodes\":[\"30\"]},{\"statusCode\":\"1\",\"status\":\"Active Coverage\",\"serviceTypeCodes\":[\"88\",\"90\",\"89\",\"54\"]}],\"benefitsInformation\":[{\"code\":\"1\",\"name\":\"Active Coverage\",\"serviceTypeCodes\":[\"30\"],\"serviceTypes\":[\"Health Benefit Plan Coverage\"],\"planCoverage\":\"BEDROCK PLAN\",\"benefitsAdditionalInformation\":{\"planNumber\":\"12345\",\"drugFormularyNumber\":\"11111\",\"planNetworkIdNumber\":\"1111111\"},\"benefitsDateInformation\":{\"plan\":\"20131015\"}},{\"code\":\"1\",\"name\":\"Active Coverage\",\"serviceTypeCodes\":[\"88\"],\"serviceTypes\":[\"Pharmacy\"]},{\"code\":\"1\",\"name\":\"Active Coverage\",\"serviceTypeCodes\":[\"90\"],\"serviceTypes\":[\"Mail Order Prescription Drug\"]},{\"code\":\"1\",\"name\":\"Active Coverage\",\"serviceTypeCodes\":[\"89\"],\"serviceTypes\":[\"Free Standing Prescription Drug\"]},{\"code\":\"1\",\"name\":\"Active Coverage\",\"serviceTypeCodes\":[\"54\"],\"serviceTypes\":[\"Long Term Care\"]}],\"x12\":\"ISA*00* *01*SomePwd *ZZ*EMDEON *ZZ*TPG00000 *231207*0238*^*00501*000000002*0*T*:~GS*HB*MTEXE*LLX1210001*20131015*2219*000000002*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*11*9d74be8a-f1e7-9cb0-3052-905d9db09298*20231207*0238~HL*1**20*1~NM1*PR*2*Unknown*****PI*00001~HL*2*1*21*1~NM1*1P*2*happy doctors group*****XX*1760854442~HL*3*2*22*0~TRN*1*000000002*9EMDEON999*~NM1*IL*1*doeone*johnone****MI*0000000000~REF*1L*0000000000~N3*~N4***~DMG*D8*18800102*~INS*Y*18*001*25*************1~HI*BK:8901:D8*BF:87200:D8*BF:5559:D8~DTP*291*D8*20131015~EB*1**30**BEDROCK PLAN~REF*18*12345~REF*FO*11111~REF*N6*1111111~DTP*291*D8*20131015~EB*1**88~EB*1**90~EB*1**89~EB*1**54~SE*26*0001~GE*1*000000002~IEA*1*000000002~\"}"
}
],
"id": "fbda7eca-46db-4240-aec1-ce222f15a04f",
"meta": {
"versionId": "76e13342-4822-4ffe-ac33-5e22ff43e9b1",
"lastUpdated": "2023-12-07T02:38:01.928Z"
}
}
Additional Resources
The RCM Service does not yet support FHIR R5 (opens in a new tab).