Skip to main content

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

Consuming the Data

The Blue Button API includes over 1300 data elements with a wide variety of data exchange use cases. Here are some basics to get you started with common data elements.

For complete implementation guidance, see the FHIR specification and the CARIN implementation guide. Our Resources page also includes links to tutorials and helpful information on FHIR.

Understanding the payload

Blue Button API search operations (like /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"
        // ...
      }
    }
  ]
}

FHIR search results are paginated because they typically contain many records. The default is 10 records in each call. You can override the default of 10 with a _count parameter in the request. The maximum 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 supplied in Bundle.link where relation = next.  

Relations for navigating through a bundle
RelationDescription
firstRetrieve the first X records in the resultset
nextRetrieve the next X records in the resultset
previousRetrieve the previous X records in the resultset
lastRetrieve the last X records in the resultset

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

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}/v2/fhir/ExplanationOfBenefit?startIndex=0&_count=10&patient=..."
    },
    {
      "relation": "next",
      "url": "{host}/v2/fhir/ExplanationOfBenefit?startIndex=10&_count=10&patient=..."
    },
    {
      "relation": "last",
      "url": "{host}/v2/fhir/ExplanationOfBenefit?&startIndex=..."
    },
    {
      "relation": "self",
      "url": "{host}/v2/fhir/ExplanationOfBenefit?&startIndex=..."
    }
  ],
}

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, the Chronic Conditions Warehouse (CCW). The resource ID is a system-level resource, held outside the resource. The Resource ID is guaranteed to be unique for a particular resource and will always be limited to one 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, there are two identifiers in the list. 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, relative URLs are provided. 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 that does not have independent existence is embedded inside another resource as a contained resource. For example, the Organization resource does not have its own endpoint. 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 typically supply a business identifier instead of a URL to an endpoint or contained resource.

In the example below, the Eob.careTeam.provider attribute contains a reference to the 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 supply Medicare-specific data points that are not part of 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 Choice of Types, where the data type depends on the definition of the extension.

In the example below, there are two extensions:

Note: In the Blue Button API, the extension URL points at an underlying valueset rather than the standard FHIR practice of the URL pointing to the StructureDefinition of the extension. This is due to historical reasons and will be revisited in future versions of Blue Button.

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. Similar to extensions, supportingInfo is like a key-value list. supportingInfo.category serves as the key and supportingInfo.code is the value. Other attributes in supportingInfo include timing[x], value[x], and reason.

Note: The CARIN Implementation Guide has chosen to use supportingInfo over extensions. The CARIN IG does not define any extensions. For historical and backwards compatibility reasons, the Blue Button API provides data in both extensions and supportingInfo.

Determining claim type

The Blue Button API supplies claims data in the ExplanationOfBenefit resource for all claim types (Example: Inpatient, Outpatient, Carrier, DME, etc.)

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. There are multiple entries in the list.

Each entry is a code from a given codesystem or valueset with information about the type of claim. For example, the NCH_CLM_TYPE_CD 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:

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, which tells you 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"
            // ...
          }
        ]
      }
    }
  ]
}

bluebutton.cms.gov

official website of the U.S. Department of Health and Human Services and the Centers for Medicare & Medicaid Services.

Looking for U.S. government information and services?
Visit USA.gov