Fetching patient data

Scope of Access

Applications receive permission to access Medicare enrollee data on a per-user basis. The Integrated Data Repository (IDR) updates enrollee claims data nearly daily. Access starts when each enrollee approves it through the Blue Button API’s authorization flow.

Duration of Access

There are 3 categories for data access duration:

Make a request

Blue Button has three main FHIR resources. Here’s how to fetch each one:

# Patient — demographics
curl "https://sandbox.bluebutton.cms.gov/v2/fhir/Patient" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Coverage — insurance and plan info
curl "https://sandbox.bluebutton.cms.gov/v2/fhir/Coverage" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# ExplanationOfBenefit — 10 claims at a time
curl "https://sandbox.bluebutton.cms.gov/v2/fhir/ExplanationOfBenefit" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

For the full list of endpoints and parameters, see the Swagger docs.

Read the response

Search operations (/Patient, /ExplanationOfBenefit) return a FHIR Bundle. A Bundle is a container that holds a list of matching resources.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 99,
  "entry": [
    {
      "resource": {
        "resourceType": "ExplanationOfBenefit",
        "id": "carrier--123"
      }
    },
    {
      "resource": {
        "resourceType": "ExplanationOfBenefit",
        "id": "carrier--456"
      }
    }
  ]
}

Use the following fields to work with the response:

• total the number of resources that match your query.
• entry the list of matching resources. Results are paginated; the default page size is 10 resources.
• entry[].resource a complete FHIR resource

Read operations with an ID (/Patient/-9985028219431) return a single resource directly, not wrapped in a Bundle.

The FHIR ID in your request must match the enrollee who authorized your application. You cannot substitute another enrollee’s FHIR ID and retrieve their data. If you request an unauthorized FHIR ID, the API returns an error, not another enrollee’s records. Each enrollee authorizes access only to their own data.

Working with identifiers

In FHIR, the difference between the Resource.id (resource ID) and identifier attributes within a resource can be confusing.

• Resource ID: In the Blue Button API, the resource ID is an internal identifier from the source database, IDR. The resource ID is a system-level resource, held outside the resource. The Resource ID is guaranteed to be unique to a particular resource and will always be a single value.
• Identifier: The identifier attribute typically provides business identifiers (or externally recognized identifiers). In the Blue Button API, the Patient.identifier attribute provides the Medicare Beneficiary ID (MBI). The MBI is the number on an enrollee’s Medicare card.

In FHIR, the identifier attribute is a list element that could supply multiple identifiers. Use discriminators to distinguish between the entries to pull your desired identifier.

For example, you can use discriminators to pull the current MBI from a Patient resource. (Enrollees are sometimes given new or replacement MBIs in situations such as identity theft.) In the Patient resource snippet below, the list includes two identifiers. Use the following discriminators to pull the current MBI:

• identifier.system = http://hl7.org/fhir/sid/us-mbi (ensures that the entry is an MBI)
• identifier.type.coding[n].extension.valueCoding.code = current

Patient identifier example:

{
  "identifier": [
    {
      "system": "http://hl7.org/fhir/sid/us-mbi",
      "type": {
        "coding": [
          {
            "code": "MC",
            "extension": [
              {
                "url": "https://bluebutton.cms.gov/resources/codesystem/identifier-currency",
                "valueCoding": {
                  "code": "current"
                }
              }
            ]
          }
        ]
      },
      "value": "<CURRENT_MBI_HERE>"
    },
    {
      "system": "http://hl7.org/fhir/sid/us-mbi",
      "type": {
        "coding": [
          {
            "code": "MC",
            "extension": [
              {
                "url": "https://bluebutton.cms.gov/resources/codesystem/identifier-currency",
                "valueCoding": {
                  "code": "historic"
                }
              }
            ]
          }
        ]
      },
      "value": "<HISTORIC_MBI_HERE>"
    }
  ]
}

Example FHIRPath expression for pulling the current MBI:

Patient.identifier
  .where(type.coding.extension('https://bluebutton.cms.gov/resources/codesystem/identifier-currency').valueCoding.code='current')
  .where(system='http://hl7.org/fhir/sid/us-mbi')
  .value

Working with references

The Blue Button API uses both literal and logical (FHIR references to refer to other resources/data external to the resource.

Literal references

For literal references, use relative URLs. In the sample EOB resource below, the Eob.patient attribute contains a relative URL reference, Patient/123. Append this path to the base FHIR URL to perform a Patient read operation.

Literal reference example:

{
  "resource": {
    "resourceType": "ExplanationOfBenefit",
    "id": "carrier--10045426206",
    // ...
    "patient": {
      "reference": "Patient/123"
    }
  }
}

Contained resources

The Blue Button API also uses fragments and contained resources. A resource without independent existence is embedded inside another resource as a contained resource.

For example, the Organization resource has no endpoint of its own. Instead, it is supplied as a contained resource with EOB. In the example EOB resource below, the Organization resource is within the Eob.contained attribute, and the Eob.provider attribute has a # reference to contained.id (#provider-org).

Contained resource example:

{
  "contained": [
    {
      "active": true,
      "id": "provider-org",
      "identifier": [
        {
          "type": {
            "coding": [
              {
                "code": "PRN",
                "system": "http://terminology.hl7.org/CodeSystem/v2-0203"
              }
            ]
          }
        }
      ]
    }
  ],
  // ...
  "provider": {
    "reference": "#provider-org"
  }
},

Logical references

Logical references usually provide a business identifier rather than a URL to an endpoint or a contained resource.

In the example below, the Eob.careTeam.provider attribute contains a reference to the National Provider Identifier (NPI) for the practitioner. (Note: The Blue Button API does not support a /Practitioner endpoint.)

Logical reference example:

{
  "careTeam": [
    {
      "provider": {
        "identifier": {
          "type": {
            "coding": [
              {
                "code": "npi",
                "display": "National Provider Identifier",
                "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType"
              }
            ]
          },
          "value": "123"
        }
      }
    }
  ]
}

Extensions and SupportingInfo

The Blue Button API supplies many data points using FHIR extensions. Extensions are information that is not part of the basic definition of the FHIR resource. They’re often very specific to a use case or situation. For example, the Blue Button API uses extensions to provide Medicare-specific data points not included in the standard FHIR specification.

All Blue Button API resources include extensions. Extensions are like a key-value list, where the extension URL is the key. In an extension, the value attribute is defined as a Choice of Types, and the data type depends on the extension’s definition.

In the example below, there are two extensions:

• NCH Near Line Record Identification Code provides the value as a valueCoding type.
• Carrier or MAC Number.

Extension example:

{
  "extension": [
    {
      "url": "https://bluebutton.cms.gov/resources/variables/nch_near_line_rec_ident_cd",
      "valueCoding": {
        "code": "O",
        "display": "Part B physician/supplier claim record (processed by local carriers; can include DMEPOS services)",
        "system": "https://bluebutton.cms.gov/resources/variables/nch_near_line_rec_ident_cd"
      }
    },
    {
      "url": "https://bluebutton.cms.gov/resources/variables/carr_num",
      "valueIdentifier": {
        "system": "https://bluebutton.cms.gov/resources/variables/carr_num",
        "value": "15202"
      }
    }
  ]
}

SupportingInfo attribute

The supportingInfo attribute is a standard element in the FHIR EOB resource. Like extensions, supportingInfo is a key-value list. supportingInfo.category is the key, and supportingInfo.code is the value. Other attributes in supportingInfo include timing[x], value[x], and reason.

Determine claim type

The Blue Button API provides claims data in the ExplanationOfBenefit resource for all claim types (e.g., Inpatient, Outpatient, Carrier, DME).

To determine the type of a given claim, inspect the Eob.type attribute. Eob.type is a CodeableConcept, which provides data as a list of codings. The list contains multiple entries.

Each entry is a code from a given codesystem or valueset that describes the claim type. For example, the NCHCLMTYPECD codesystem uses the code 71 for a carrier claim. The Blue Button API eob-type valueset uses a code of CARRIER for a carrier claim.

Claim type example:

{
  "type": {
    "coding": [
      {
        "code": "71",
        "display": "Local carrier non-durable medical equipment, prosthetics, orthotics, and supplies (DMEPOS) claim",
        "system": "https://bluebutton.cms.gov/resources/variables/nch_clm_type_cd"
      },
      {
        "code": "CARRIER",
        "system": "https://bluebutton.cms.gov/resources/codesystem/eob-type"
      }
      // ...
    ]
  }
}

For more information about determining claim types, see the following coding system reference links:

• EOB type
• NCH Claim Type Code variable
• FHIR Claim Type value set

Linking items

The item data element in the EOB resource supplies a list of entries describing products/services provided. You can link each entry in the list to other parts of the EOB using the item.*sequence elements.

For example, Eob.item.diagnosisSequence links to Eob.diagnosis.sequence, indicating that this product/service is linked to the corresponding diagnosis. In the partial EOB example below, the item is linked to diagnosis 1 and careTeam member 3.

Linking item example:

{
  "item": [
    {
      "adjudication": [
        // ...
      ],
      "diagnosisSequence": [
        1
      ],
      "careTeamSequence": [
        3
      ]
      // ...
    }
  ],
  "diagnosis": [
    {
      "sequence": 1,
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "code": "Z0000",
            "display": "ENCNTR FOR GENERAL ADULT MEDICAL EXAM W/O ABNORMAL FINDINGS"
          }
        ]
        // ...
      }
    }
  ],
  "careTeam": [
    {
      "sequence": 1
      // ...
    },
    {
      "sequence": 2
      // ...
    },
    {
      "sequence": 3,
      "provider": {
        "identifier": {}
        // ...
      },
      "role": {
        "coding": [
          {
            "code": "performing",
            "display": "Performing provider"
            // ...
          }
        ]
      }
    }
  ]
}

Understanding the payload

Blue Button API search operations such as /Patient, /ExplanationOfBenefit, and /ExplanationOfBenefit?patient=123, return data in FHIR Bundles. A FHIR bundle is a container resource that includes a collection of FHIR resources. You can grab each resource by looping through the Bundle.entry list attribute.

Read calls such as /Patient/123 return a single resource.

FHIR Bundle example:

{
  "resourceType": "Bundle",
  "id": "123",
  // ...
  "type": "searchset",
  "total": 99,
  "entry": [
    {
      "resource": {
        "resourceType": "ExplanationOfBenefit",
        "id": "carrier--123"
        // ...
      }
    },
    {
      "resource": {
        "resourceType": "ExplanationOfBenefit",
        "id": "carrier--456"
        // ...
      }
    }
  ]
}

Navigating through a bundle

FHIR search results are paginated by default, with 10 records per call. You can override the default of 10 with a count parameter in the request. The maximum number of records allowed is 50.

To navigate forward and backward through the bundle, use the URLs provided in Bundle.link, as described in the table below. For instance, to get the next X records, use the URL provided in Bundle.link where relation = next.

In the example below, the Bundle.total attribute shows that there are 89 records in the results. However, the Bundle.entry array contains only the first 10 records.

For more information on Bundles and FHIR search results, see FHIR v4.3.0 Bundle and FHIR v4.3.0 Managing Returned Resources Bundle navigation example:

{
  "resourceType": "Bundle",
  "id": "5e5844c4-d3e2-44ca-8c87-77efccc5d60d",
  // ...
  "total": 89,
  "link": [
    {
      "relation": "first",
      "url": "{host}/v3/fhir/ExplanationOfBenefit?startIndex=0&_count=10&patient=..."
    },
    {
      "relation": "next",
      "url": "{host}/v3/fhir/ExplanationOfBenefit?startIndex=10&_count=10&patient=..."
    },
        {
      "relation": "self",
      "url": "{host}/v3/fhir/ExplanationOfBenefit?&startIndex=..."
    }
  ],
}

Working with partially adjudicated claims

Partially adjudicated claims are also called non-Final Action claims and show a claim’s progress through the adjudication process. CARIN Blue Button 2.1.0 profiles, the format the Blue Button API uses, represent partially adjudicated claims (also called non-Final Action claims) using the ExplanationOfBenefit resource.

Disclaimers for non-Final Action claims:

• Claims with outcome = partial may contain nonsensical values in coded elements, such as invalid CPT/HCPCS codes and invalid diagnosis codes, due to their non-finalized nature. This is more likely in claims with a claim type code of 1XXX. Use ExplanationOfBenefit.outcome to determine the processing stage of a claim.
• Not all fields are available in non-Final Action claims. Most of these relate to benefit balance information that isn’t available until a claim has been fully adjudicated. Ongoing work is improving parity between data from the Shared Systems and the National Claims History.

Blue Button exposes three search parameters for filtering metadata.

The metadata field, source, identifies the CMS system from which the information originated:

• NCH = National Claims History (All adjudicated claims for Parts A + B)
• FISS = Fiscal Intermediary Shared System (Partially Adjudicated Institutional Claims)
• MCS = Multi-Carrier System (Partially Adjudicated Professional Claims)
• VMS = Viable Information Processing Systems (ViPS) Medicare Shared System (Partially Adjudicated DME claims)
• DDPS = Drug Data Processing System (All Part D claims)
• MAP = Medicare Adjudication Portal (some professional claims)

_source

Filtering by source filters on the Meta.source key. Blue Button supports both AND and OR operations. (Filtering by AND is useless, however.)

The sources to filter on, and their constituent data, are below.

_tag

Blue Button supports two tags, System-Type and Final-Action, which need to be sent in token format (e.g., system|code). Blue Button supports both AND and OR operations.

_security

_security allows you to target sensitive substance use claims data. v3 populates a Meta.security token on data that is “sensitive” on the basis of the ACO-OS sensitive data list (Appendix A).

By default, the behavior includes all claims without any filtering.

How to use Shared Systems data

Without any filters, Blue Button returns Part A, B, and D data from both Shared Systems and the National Claims History (NCH) by default. Use the metadata filters described above to change this behavior, set API-specific defaults, etc.

Filtering Part A / B data using source and tag

You can filter data by a claim’s source system using either the _source or _tag parameter.

vs.

Working with digital insurance card data

The endpoint, /v3/fhir/Patient/{patient}/$generate-insurance-card allows developers to surface digital proof of Medicare coverage to enrollees, providing details on the types of coverage available.

This endpoint references the CARIN Digital Insurance Card Implementation Guide. It returns a bundle that includes /Patient and /Coverage resources conformant to the Digital Insurance Guide profile. You can find examples of this in the Blue Button Swagger resource.