Coverage

Goal

Coverage is a FHIR Resource that describes the financial terms of a specific health insurance plan for a specific person.

We will use Flexpa Link and Flexpa API to search for Coverage belonging to a specific patient. Accessing a patient's coverage can aid in workflows such as:

Recommending services based on costs, co-pays, or features of a specific health plan
Validating that a patient has an active health plan
Retrieving information commonly found on an health insurance card such as Member ID and Group ID

Getting started

Coverage is directly represented in patient access APIs as a FHIR Resource. We can make HTTP requests to Flexpa API to search for and find coverage belonging to a particular patient. Patients authorize your app to access their Coverage via Flexpa Link. At the end of the Flexpa Link flow you'll have:

An access token that is required for all requests to Flexpa API
A patient id, that is required to query FHIR resources directly related to the patient

Searching for a Patient's Coverage

Flexpa API can be used to search for Coverage after a patient has authorized access via Flexpa Link. Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource. To search for coverage belonging to a particular patient, you must provide a patient value as a query parameter.

You can retrieve the patient id by either:

Saving the patient id obtained through the Flexpa Link flow
Introspecting the access token

ACCESS_TOKEN=... # replace with the access token you obtained at the end of the Flexpa Link flow
PATIENT_ID=Patient/A000123 # replace with the patient id you obtained at the end of the Flexpa Link flow

curl "https://api.flexpa.com/fhir/Coverage?patient=$PATIENT_ID" \
  -H "Authorization: $ACCESS_TOKEN"

Response Type

The return type of querying the coverage endpoint is a searchset bundle. Technically, a searchset bundle may contain different types of resources (e.g., Coverage, Patient, etc) in the entry field. When iterating through entry it is best practice to inspect each resourceType field to ensure you are dealing with the expected resource.

Sample Response

{
  "resourceType": "Bundle",
  "id": "84ff19926c1a4ead92f24e7a86216093",
  "meta": {
    "lastUpdated": "2022-06-10T00:50:55.2024996+00:00"
  },
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://fhir.humana.com/sandbox/api/Coverage?patient=74532b683658335246434e495a53425462476c5741673d3d"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir.humana.com/sandbox/api/Coverage/3a4523b9d83a5f5d36c74a9e5c2d222894dd38af14383673ad4ace5ed79fa662",
      "resource": {
        "resourceType": "Coverage",
        "id": "3a4523b9d83a5f5d36c74a9e5c2d222894dd38af14383673ad4ace5ed79fa662",
        "meta": {
          "versionId": "497",
          "lastUpdated": "2022-06-09T07:19:27.905+00:00",
          "source": "https://fhir.humana.com/documentation/glossary/HumanaDataSource",
          "tag": [
            {
              "system": "https://www.hl7.org/fhir/patient.html",
              "code": "Patient/74532b683658335246434e495a53425462476c5741673d3d"
            },
            {
              "system": "https://fhir.humana.com/documentation/glossary/lastRefreshedOn",
              "code": "2022-06-09T07:19:26.906Z"
            }
          ]
        },
        "status": "cancelled",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
              "code": "DRUGPOL",
              "display": "drug policy"
            }
          ],
          "text": "drug policy"
        },
        "beneficiary": {
          "reference": "Patient/74532b683658335246434e495a53425462476c5741673d3d"
        },
        "period": {
          "start": "2021-01-01",
          "end": "2021-12-31"
        },
        "payor": [
          {
            "display": "Humana"
          }
        ],
        "class": [
          {
            "type": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                  "code": "subplan"
                }
              ]
            },
            "value": "R0865-001-000-2021"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "fullUrl": "https://fhir.humana.com/sandbox/api/Coverage/36bcd2164f4e41fe3bd9e700fe1231f83f4cceacdee5ee76726b026949f99105",
      "resource": {
        "resourceType": "Coverage",
        "id": "36bcd2164f4e41fe3bd9e700fe1231f83f4cceacdee5ee76726b026949f99105",
        "meta": {
          "versionId": "404",
          "lastUpdated": "2022-06-09T07:19:27.864+00:00",
          "source": "https://fhir.humana.com/documentation/glossary/HumanaDataSource",
          "tag": [
            {
              "system": "https://www.hl7.org/fhir/patient.html",
              "code": "Patient/74532b683658335246434e495a53425462476c5741673d3d"
            },
            {
              "system": "https://fhir.humana.com/documentation/glossary/lastRefreshedOn",
              "code": "2022-06-09T07:19:26.906Z"
            }
          ]
        },
        "text": {
          "status": "generated",
          "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">DENTAL</div>"
        },
        "identifier": [
          {
            "type": {
              "text": "MemberIDDependentCode"
            },
            "system": "https://fhir.humana.com/documentation/glossary/memberIDDependentCode",
            "value": "01",
            "assigner": {
              "display": "Humana"
            }
          },
          {
            "type": {
              "text": "MemberIdBase"
            },
            "system": "https://fhir.humana.com/documentation/glossary/memberIdBase",
            "value": "179683109",
            "assigner": {
              "display": "Humana"
            }
          },
          {
            "type": {
              "text": "DivisionId"
            },
            "value": "77600020",
            "assigner": {
              "display": "Humana"
            }
          },
          {
            "type": {
              "text": "GroupId"
            },
            "value": "715824",
            "assigner": {
              "display": "Humana"
            }
          },
          {
            "use": "official",
            "type": {
              "text": "NetworkId"
            },
            "value": "439891",
            "assigner": {
              "display": "Humana"
            }
          },
          {
            "use": "usual",
            "type": {
              "text": "NetworkId"
            },
            "value": "HUMANA HMO TECHNETIUM MEMBER PLAN",
            "assigner": {
              "display": "Humana"
            }
          }
        ],
        "status": "cancelled",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
              "code": "DENTAL",
              "display": "dental care policy"
            }
          ],
          "text": "dental care policy"
        },
        "subscriberId": "179683109-01",
        "beneficiary": {
          "reference": "Patient/74532b683658335246434e495a53425462476c5741673d3d"
        },
        "dependent": "01",
        "relationship": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
              "code": "self",
              "display": "Self"
            }
          ],
          "text": "Self"
        },
        "period": {
          "start": "2021-01-01",
          "end": "2021-12-31"
        },
        "payor": [
          {
            "display": "Humana"
          }
        ],
        "class": [
          {
            "type": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                  "code": "group"
                }
              ]
            },
            "value": "715824"
          },
          {
            "type": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                  "code": "plan"
                }
              ]
            },
            "value": "HU300007",
            "name": "DENTAL"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Notable Fields

A coverage response contains many fields. You can get an exhaustive list and explanation of each field here. Some notable fields:

entry - A collection of coverages (see response type on best practice of checking resourceType)
entry[i].status - A string representing the status of the coverage, can have a value of "active", "cancelled", "draft", "entered-in-error"
entry[i].type - An object describing the coverage category (e.g., drug policy, dental policy, automobile injury policy, etc)
entry[i].period - A period datatype describing the coverage's start and end date
entry[i].identifier - (optional) The primary identifier of the insured and the coverage. May contain the insured's member id, group id, etc.

Next Steps

Flexpa Link

Flexpa Link is a client-side component to help your users link health plan data sources

Build with Flexpa Link →

API Reference

Use Flexpa API as a unified API to access Explanation of Benefits and more

Build with Flexpa API →