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
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 payerSet the
include_full_response
parameter equal totrue
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. The request will default to code 17 which maps to primary care. |
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”
.
- For example: “Aetna Better Health of Illinois”
Updated 5 months ago