GuidesAPI ReferenceTry Ribbon!
Guides

Deductible Check

Endpoint for checking where a member is in their current deductible and out of pocket spend.

Suggest Edits

❗️

THIS PRODUCT HAS BEEN SUNSETTED

Please upgrade to using our new Eligibility Check (not a breaking change). Our Eligibility Check is an improved version of this sunsetted product, providing higher data quality and the addition of copay and coinsurance summary fields.

Overview

Description: The deductible check endpoint returns a member's deductible, out of pocket maximum spend, and how much of their deductible they have already spent.

Endpoints: Primary: /v1/deductible Reference: /v1/insurance_partners

Status: Live -- Please Contact Us to Learn More

Example use-case: Inform a member of their current progress against their deductible, so they can better estimate their out of pocket costs.

Important: Ribbon will be sunsetting the Deductible v1 endpoint at the end of July 2022 due to clearinghouse dependencies. Please contact us to learn more about how we can support you through the easy migration to our new and improved eligibility endpoint.

Improved Eligibility Endpoint: Click here to learn more about Ribbon's new and improved eligibility endpoint.

Example Request

The call below takes a member's basic insurance information as parameters in order to check their deductible and out of pocket status:

  • First Name
  • Last Name
  • Birth Date
  • Insurance Partner
  • Member ID
curl -X POST \
  https://api.ribbonhealth.com/v1/deductible \
  -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/deductible?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.

  • "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.
  • "request_id" | The unique log identifier for the given 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
    },
    "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"
            }
        }
    },
    "request_id": "5d881446-466e-47ab-9208-2caed2fbd98d"
}

Common Error Codes

Within the "status" field, we include a field called "error" to display any relevant errors for the given /deductible/ 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"Core fields (deductible details and out of pocket details) returned by the payer are invalid - for example negative spend against a deductible.

Check For Insurances

Leverage the /insurance_partner/ 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/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/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/insurance_partners/aetna_better_health

Endpoint Response

The following fields are returned by the /insurance_partner/ endpoint:

  • “insurance_partner”
    • For example: “aetna_better_health_il”
  • “insurance_partner_display”
    • For example: “Aetna Better Health of Illinois”
  • “status”
    • “unknown” - status unknown

❗️

As of December 1, 2020 our "status" field will no longer be populated with live payer eligibility statuses

We will no longer receive real-time payers' eligibility statuses from our clearinghouse partner, and therefore the "status" field within the /insurance_partners/ will be populated universally as "unknown".

Updated over 1 year ago