🚧
The RCM Service is currently in beta.

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
payerIdResponse Details
00001This is a canned response that returns a single coverage plan. This will work for any payer.
000002This is a canned response that returns a badly formatted 271. This will work for any payer.
00003This 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.
00004This is a canned response that returns AAA Not Eligible For Inquiries. This will work for any payer.
00005This is a canned response that contains non-printable characters which we need to make sure we can parse. This will work for any payer.
00006A system error from the Payer. AAA segment in the 2000A Information Source Loop with AAA01 = Y, AAA03 = 42 and AAA04 = R.
00007This is a canned response that returns a single coverage plan with unused fields. This will work for any payer.
000008This 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.
00009This returns a canned 271 response where the patient is a dependent.
000010Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Date of Service and service type as input parameters.
000011Rehabilitation Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Last Name Date of Service and service type as input parameters.
000012Medical Care Inquiry: A 270 request with provider ID, subscriber ID, Date of Service and service type as input parameters.
000013Rehabilitation 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.
000014Vision (Optometry) Inquiry: A 270 request with provider ID, subscriber ID, SSN, DOB, Date of Service and service type as input parameters.
000015Home Health Care Inquiry: A 270 request with provider ID, subscriber ID, DOB, Date of Service and service type as input parameters.
000016Pharmacy Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Last Name, Date of Service and service type as input parameters.
000017Medical Care Inquiry: A 270 request with provider ID, subscriber ID, Date of Service and service type as input parameters.
000018Emergency 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.
000019Rehabilitation Inquiry: A 270 request with provider ID, subscriber SSN, DOB, Date of Service and service type as input parameters.
000020Rehabilitation Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, Date of Service and service type as input parameters.
000021Rehabilitation Inquiry: A 270 request with provider ID, DOB, First Name, Last Name Date of Service and service type as input parameters.
000022Medical Care Inquiry: A 270 request with provider ID, subscriber ID, Date of Service and service type as input parameters.
000023Health 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.
000024Health Benefit Plan Coverage Inquiry: A 270 request with provider ID, subscriber ID, First Name, Date of Service and service type as input parameters.
000025Rehabilitation Inquiry: A 270 request with provider ID, subscriber ID, Last Name, Date of Service and service type as input parameters.
000026Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, service type and diagnosis code as input parameters.
000027Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, service type and provider code as input parameters.
000028Hospital Inquiry: A 270 request with provider ID, subscriber ID, DOB, First Name, service type and provider information as input parameters.
000029Health Benefit Plan Coverage Inquiry: A 270 request with Invalid Provider ID.
000030Health Benefit Plan Coverage Inquiry: A 270 request with Invalid Patient Information.
000031Health Benefit Plan Coverage Inquiry: A 270 request with Inactive Coverage date as service date.
000032Health Benefit Plan Coverage Inquiry: A 270 request with Duplicate. Subscriber ID.
000033Health Benefit Plan Coverage Inquiry: A 270 request with Invalid Provider ID.
000034Rehabilitation Inquiry: A 270 request with Subscriber ID, Dependent first Name and service type code as input parameters.
000035Pharmacy Inquiry: A 270 request with Subscriber ID, Dependent first Name and service type as input parameters.
00036Florida Medicaid: Sample response.
000036Home Health Care Inquiry: A 270 request with Subscriber ID, Dependent DOB and service type as input parameters.
000037Psychiatric Inquiry: A 270 request with Subscriber ID, Dependent First Name and service type as input parameters.
000038Rehabilitation Inquiry: A 270 request with Subscriber ID, Dependent DOB, Dependent Last Name and service type as input parameters.
000039Different Deductible at 30 and other STC.
000040EB 1 with no benefits (Active Coverage) and EB I (Non Covered).
000041Test EB 6 (Inactive) and EB W (Other Source of Data).
000042EB R — other additional payer. Sample use case for standard Medicaid benefit.
000043EB W response (Other source of Data).
000044High Out of pocket remaining but no deductible in response.
000045Low Deductible High Premium — many different copayments.
000046Low Deductible High Premium with no coinsurance.
000047Low Deductible High Premium.
000048Low Deductible with no copayment.
000049Multiple Services.
000050No Deductible, High Out of Pocket Remaining, only Copay and coinsurance.
000051No Deductible, only copay for 33,98, UC.
000052No Deductible, No copayment.
000053Plan with active coverage but no patient responsibility.
000054Response with AD time period 25.
000055Too many deductibles at service levels.
000056Uniquely formatted EB segment.
000067Sample use case from PAA.
000068Sample use case 2 from PAA.
000069Sample Use case for EB V (Cannot Process).
000070Sample Use case for EB U (Contact Following Entity for Eligibility or Benefit Information).
000074Sample Use case for Connecticut Medicaid.
000081Sample response for WellCare.
000082Sample response for Blue Cross Blue Shield Georgia.
000083Sample response for Humana.
ABHFLSample use case for Aetna Better Health of Florida.
ABHKYSample use case for Aetna Better Health of Kentucky.
ABHLASample use case for Aetna Better Health of Louisiana.
ABHMOSample use case for Aetna Better Health of Missouri.
AETNXSample response for AETNA.
BCCTCSample use case for Blue Cross Blue Shield Connecticut.
BCNJCSample response for BCBS of New Jersey (Horizon).
CABCA 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.
CIGNAA sample response for CIGNA for dependent.
CMSMEDA 270 request with additional fields. Sample response for Medicare Part A/Medicare Part B.
CNTCRSample use case for Connecticare Inc.
COVONSample response for Coventry.
CTSample use case for Connecticut Medicaid.
DENTALSample response for benefits from Dental Payer.
HUMSample response for Humana.
ILMSASample use case for Aetna Better Health of Illinois.
ISCAMSample response for Medi-CAL Portal connection.
MA/MBSample response for Medicare Part A/Medicare Part B.
MEDXSample response for MEDEX.
MMSISample use case for Mayo.
TRICESample response for Tricare.
TXSample response for Texas Medicaid.
TXBCBSSample response for Blue Advantage HMO.
UHCSample 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.

An example CoverageEligibilityResponse.insurance.item (opens in a new tab):

{
  "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"
          }
        ]
      }
    }
  ]
}

The example shows 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.

Contained Resources

ZapEHR completes the CoverageEligibilityResponse resource using Contained Resources (opens in a new tab) for the following reference properties:

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).