HealthPartners logo Overview

The HealthPartners Patient Access API lets patients securely access their health information electronically. This API gives patients easy access to data about their coverage, insurance plan, medications and more. It's compliant with the latest interoperability standards set forth by Centers for Medicare & Medicaid Services (CMS-9115-F). The Patient Access API implements FHIR V4 standards, SMART on FHIR and OAuth 2.0 for secure authentication, and recommended Implementation Guides for a standardized, consumer-directed data exchange.

Using the API

To use the HealthPartners Patient Access API, developers must first register their application within the developer portal. Once registered, developers can make authorized requests to the API to access patient data. All requests to the Patient Access API require an OAuth bearer token obtained using the Authorization Code flow. The bearer token must be sent in the HTTP Authorization header.

For development and testing, use the sandbox base URL described on the Smart Auth page. Production access requires approval. The production base URL for the Patient Access API is: https://api-developerportal.healthpartners.com/interop/external/fhir.

Read a resource

To read (fetch) a resource, use the following syntax:

GET [base]/[Resource]/[id]
Authorization: Bearer [access_token]
  • GET is the HTTP verb
  • [base] is the base URL for the API
  • [Resource] is the type of FHIR resource being accessed (e.g., Patient, Observation, etc.)
  • [id] is the unique identifier for the specific resource instance
  • [access_token] is an OAuth bearer token obtained via the Authorization Code flow sent in the HTTP Authorization header
Example read request 

GET https://api-developerportal.healthpartners.com/interop/external/fhir/Patient/12345
Authorization: Bearer [access_token]
 Example response 
{
  "resourceType": "Patient",
  "id": "12345",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient|2.1.0"
    ]
  },
  "name": [
    {
      "family": "Doe",
      "given": [
        "John"
      ]
    }
  ],
  "gender": "male",
  "address": [
    {
      "line": [
        "123 Main St"
      ],
      "city": "Anytown",
      "state": "MN",
      "postalCode": "12345"
    }
  ]
}
 Search for a resource

To search for a resource, use the following syntax:

GET [base]/[Resource]?[parameters]
Authorization: Bearer [access_token]
  • GET is the HTTP verb
  • [base] is the base URL for the API
  • [Resource] is the type of FHIR resource being accessed (e.g., Patient, Observation, etc.)
  • [parameters] are the search parameters used to filter results, in the format of key=value pairs (e.g., ?gender=male&identifier=12345)
  • [access_token] is an OAuth bearer token obtained via the Authorization Code flow sent in the HTTP Authorization header
Example search request 

GET https://api-developerportal.healthpartners.com/interop/external/fhir/Patient/?gender=male&identifier=12345
Authorization: Bearer [access_token]
Example response 
{
  "resourceType": "Patient",
  "id": "12345",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient|2.1.0"
    ]
  },
  "name": [
    {
      "family": "Doe",
      "given": [
        "John"
      ]
    }
  ],
  "gender": "male",
  "address": [
    {
      "line": [
        "123 Main St"
      ],
      "city": "Anytown",
      "state": "MN",
      "postalCode": "12345"
    }
  ]
}
 Patient-everything request

Another way to retrieve patient information is via the Patient-everything operation. This operation provides a view of all resources related to a patient. The results come back in phases. After all results from a phase are returned, the next link in the response bundle will point to the call to initiate the next phase.

To use the Patient-everything operation, use the following syntax: 

GET [base]/Patient/[id]/$everything
Authorization: Bearer [access_token]
  • GET is the HTTP verb
  • [base] is the base URL for the API
  • [id] is the unique identifier for the specific Patient requested
  • [access_token] is an OAuth bearer token obtained via the Authorization Code flow sent in the HTTP Authorization header
Example Patient-everything request 

GET https://api-developerportal.healthpartners.com/interop/external/fhir/Patient/12345/$everything
Authorization: Bearer [access_token]
Example Patient-everything response 
{
  "resourceType": "Bundle",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient|2.1.0"
    ]
  },
  "link": [
    {
      "relation": "next",
      "url": "https://api-developerportal.healthpartners.com/interop/external/fhir/..."
    }
  ],
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "12345",
        "name": [
          {
            "family": "Doe",
            "given": [
              "John"
            ]
          }
        ],
        "gender": "male",
        "address": [
          {
            "line": [
              "123 Main St"
            ],
            "city": "Anytown",
            "state": "MN",
            "postalCode": "55555"
          }
        ]
      }
    }
  ]
}
 Implementation Guides

The following Implementation Guides (IGs) are used to implement the HealthPartners Patient Access API:

US Core 6

The US Core Implementation Guide is based on FHIR Version R4. It defines the minimum requirements for accessing patient data while following CMS interoperability guidelines. The HealthPartners Patient Access API implements version 6 of the US Core IG.

CARIN Consumer Directed Payer Data Exchange

The CARIN Consumer Directed Payer Data Exchange Implementation Guide (CARIN IG for Blue Button) is maintained by the CARIN Alliance and provides FHIR R4-based profiles for consumer-directed exchange of Claims and ExplanationOfBenefit data. It specifies requirements for profiles such as claims or encounters, along with access via OAuth 2.0 and SMART on FHIR.

DaVinci Payer Data Exchange

The DaVinci Payer Data Exchange Implementation Guide (PDex IG) is maintained by the HL7 DaVinci Project and provides FHIR R4-based profiles for exchanging clinical data between payers and with providers.

DaVinci Payer Data Exchange (PDex) U.S. Drug Formulary

The DaVinci U.S. Drug Formulary Implementation Guide (PDex IG) defines a standard way to represent and share health plan drug formulary information using FHIR R4-based profiles. A drug formulary is a list of brand-name and generic prescription drugs that are fully or partially covered with a health insurance plan.

Helpful links CMS-9115-F: Interoperability and Patient Access Final Rule HL7 FHIR Release 4 US Core Implementation Guide CARIN Consumer Directed Payer Data Exchange DaVinci Payer Data Exchange DaVinci Payer Data Exchange (PDex) U.S. Drug Formulary