Eligibility Check

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
Practice Type Code (optional parameter, if unspecified the request will default to Code 17)

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 Field	Description
`status`	Indicates whether the response is valid and/or if there are any errors (i.e. insurance_partner is unable to respond).
`plan_info`	Includes the returned plan name for the selected member, whether that plan is active, and the start/end dates for the plan (if applicable).
`deductible_detail`	Deductible data broken out by individual vs family as well as in-network vs out-of-network.
`out_of_pocket_detail`	Out of pocket data broken out by individual vs family as well as in-network vs out-of-network.
`<dynamic_name>_summary`	Practice type summary for a specific service that includes a member's copay and coinsurance information. If unspecified, the request will default to code 17 which maps to primary care. Reference Ribbon's practice type code mappings to receive information on various services.
`request_id`	The 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”

Check for Practice Type Codes

Ribbon utilizes Practice Type codes, which are a more user-friendly abstraction of X-12 service type codes. This functionality enables users to retrieve a member's Copay and Coinsurance information for service types such as physical therapy, emergency services, etc.

Document Use Cases

Leverage the document linked below to retrieve a member's Copay and Coinsurance information for a specific service by inputting the relevant practice type code into the API call request. Please note that this data is only available via the API it if is available via the payer.

Document Column	Description
Practice Type Name	When available, these correspond directly to industry standard X-12 codes.
Practice Type Value	Practice type code mappings produced by Ribbon Health's clearinghouse partner.
Ribbon Summary Object	The name of the field users can expect to see returned in the call request.

docs.google.com

[External] Practice Type Codes

Example JSON Snippet

The example below includes part of a JSON output that is the result of inputting practice type code 94, which maps to psychotherapy, directly into the API request.

{
    "parameters": {
        "member_id": "XXXXXXXXXXXX",
        "first_name": "John",
        "last_name": "Doe",
        "birth_date": "1980-12-31",
        "insurance_partner": "MOCKPAYER",
        "practice_type_code": "94"
    },
    ...other standard eligibility fields (status, request_id, plan_info, etc.)...
    "psychotherapy_summary": {
        "in_network": {
            "copay": "40.0",
            "coinsurance": "0.0"
        },
        "out_of_network": {
            "copay": "0.0",
            "coinsurance": "0.3"
        }
    }
}

Overview

Example Request

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

Example JSON Output

Common Error Codes

Check For Insurances

Check for Practice Type Codes

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