GuidesAPI ReferenceTry Ribbon!
Guides

Eligibility Check

Suggest Edits

Overview

Description: Verifying a member's insurance coverage and benefits is a critical step in helping a member get care. Ribbon’s Eligibility Check endpoint allows you to verify a member's current insurance coverage and benefits. You can access detailed information including a member’s progress on their Deductible and Out-of-pocket, as well as Copay and Coinsurance information for different services.

Endpoints: Primary: /v1/eligibility Insurance Partner Reference: /v1/eligibility_insurance_partners

Status: Live -- Please Contact Us to Learn More

Example use-case: Inform a member of their current progress against their Deductible as well as their Copay and Coinsurance summaries so they can better estimate their out-of pocket costs.

Upgrades to our Eligibility endpoint: Ribbon's new Eligibility endpoint supports eligibility checking as well as the additional functionality of retrieving Copay and Coinsurance details for a variety of services to allow for a more granular understanding of a member's insurance coverage. These improvements also come with a significant increase in payer coverage which can be leveraged through Ribbon's new reference endpoint /v1/eligibility_insurance_partners.

Example Request

The call below takes a member's basic insurance information as parameters:

  • First Name
  • Last Name
  • Birth Date
  • Insurance Partner
  • Member ID
curl -X POST \
  https://api.ribbonhealth.com/v1/eligibility \
  -H 'Authorization: Bearer your_token' \
  -d '{
    "member_id":"000000000-00",
    "first_name":"John",
    "last_name":"Doe",
    "birth_date":"1980-12-31",
    "insurance_partner":"MOCKPAYER"
}'

👍

Add include_full_response parameter to see the full eligibility response from the payer

Set the include_full_response parameter equal to true in request URL to display the full eligibility response from the payer, including metadata like coinsurance, copays, etc.

Note: the full response will not be standardized like our core fields are (e.g. "plan_info", "deductible_detail", "out_of_pocket_detail")

An example API request with the include_full_response parameter is as follows:

curl -L -X POST 'https://api.ribbonhealth.com/v1/eligibility?include_full_response=true' \
-H 'Authorization: Bearer your_token' \
-H 'Content-Type: application/json' \
--data-raw '{
    "member_id":"XXXXXXXXXXXX",
    "first_name":"John",
    "last_name":"Doe",
    "birth_date":"1980-12-31",
    "insurance_partner":"MOCKPAYER"
}'

Example JSON Output

In the example response below, you can see Mr. Doe's current insurance status.

Response FieldDescription
statusIndicates whether the response is valid and/or if there are any errors (i.e. insurance_partner is unable to respond).
plan_infoIncludes the returned plan name for the selected member, whether that plan is active, and the start/end dates for the plan (if applicable).
deductible_detailDeductible data broken out by individual vs family as well as in-network vs out-of-network.
out_of_pocket_detailOut of pocket data broken out by individual vs family as well as in-network vs out-of-network.
<dynamic_name>_summaryPractice type summary for a specific service that includes a member's copay and coinsurance information. The request will default to code 17 which maps to primary care.
request_idThe unique log identifier for the given response.

Please note that if the value is returned as null it means that the insurance_partner did not pass through parsable information in their raw EDI 271 response.

{
    "parameters": {
        "member_id": "XXXXXXXXXXXX",
        "first_name": "John",
        "last_name": "Doe",
        "birth_date": "1980-12-31",
        "insurance_partner": "MOCKPAYER"
    },
    "status": {
        "is_valid": true,
        "error": null
    },
    "request_id": "40610978",
    "plan_info": {
        "insurance_partner": "MOCKPAYER",
        "plan_name": "Open Choice",
        "is_active": true,
        "plan_start_date": "2012-02-01",
        "plan_end_date": null
    },
    "deductible_detail": {
        "individual": {
            "in_network": {
                "spend": "16.43",
                "maximum": "3000",
                "remaining": "2983.57"
            },
            "out_of_network": {
                "spend": "16.43",
                "maximum": "6000",
                "remaining": "5983.57"
            }
        },
        "family": {
            "in_network": {
                "spend": "43.91",
                "maximum": "6000",
                "remaining": "5956.09"
            },
            "out_of_network": {
                "spend": "43.91",
                "maximum": "12000",
                "remaining": "11956.09"
            }
        }
    },
    "out_of_pocket_detail": {
        "individual": {
            "in_network": {
                "spend": "16.43",
                "maximum": "3000",
                "remaining": "2983.57"
            },
            "out_of_network": {
                "spend": "16.43",
                "maximum": "12500",
                "remaining": "12483.57"
            }
        },
        "family": {
            "in_network": {
                "spend": "43.91",
                "maximum": "6000",
                "remaining": "5956.09"
            },
            "out_of_network": {
                "spend": "43.91",
                "maximum": "25000",
                "remaining": "24956.09"
            } 
    },
    "primary_care_summary": {
        "in_network": {
            "copay": "30.0",
            "coinsurance": "0.0"
        },
        "out_of_network": {
            "copay": "0.0",
            "coinsurance": "0.4"
        }
    }
}

Common Error Codes

Within the "status" field, we include a field called "error" to display any relevant errors for the given /eligibility/ call. As errors are reported directly from insurance partners, they often vary, however, see below for the most common error codes:

"error"description
"invalid_subscriber_id"User inputted "member_id" not found by insurance partner
"invalid_subscriber_name"User inputted name not found by insurance partner
"invalid_subscriber"User inputted member information not found by insurance partner
"invalid_subscriber_birth_date"User inputted "birth_date" not found by insurance partner
"payer_unable_to_respond_now"Insurance partner is experiencing temporary downtime and unable to complete the request, please try again later.
"payer_unable_to_respond"Insurance partner is unable to respond, will be investigated and resolved.
"unable_to_respond"Insurance partner error, will be investigated and resolved.
"invalid_payer_response"Fields returned by the payer are invalid so we are unable to relay the information in the response.

Check For Insurances

Leverage the /v1/eligibility_insurance_partners endpoint to see a list of all insurance partners supported by the Ribbon API or to power a drop down for your users.

Endpoint Use Cases

To see a full list of our insurance partners, you can use the following URL in a GET request:
https://api.ribbonhealth.com/v1/eligibility_insurance_partners

To search our list of insurance partners by name, you can use the search parameter in the URL as follows and you will receive a list of potential matches based on a fuzzy search:
https://api.ribbonhealth.com/v1/eligibility_insurance_partners?search=aetna

To receive information about a specific insurance partner, you can pass through the "insurance_partner" id itself, as follows:
https://api.ribbonhealth.com/v1/eligibility_insurance_partners/aetna_better_health

Endpoint Response

The following fields are returned by the v1/eligibility_insurance_partner/ endpoint:

  • “insurance_partner”
    • For example: “aetna_better_health_il”
  • “insurance_partner_display”
    • For example: “Aetna Better Health of Illinois”
      .

Updated 6 months ago