HealthPartners logo Overview

The HealthPartners Provider Directory API includes data on contracted providers and pharmacies. It's compliant with the latest interoperability standards set forth by Centers for Medicare & Medicaid Services (CMS-9115-F). The Provider Directory API implements FHIR V4 standards and recommended Implementation Guides for a standardized, consumer-directed data exchange.

Using the API

To use the HealthPartners Provider Directory API, developers must first register their application within the developer portal. Once registered, developers can make requests to the API to access provider data. All requests to the Provider Directory API require an OAuth bearer token obtained using the Client Credentials 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 Provider Directory 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., Practitioner, Organization, etc.)
  • [id] is the unique identifier for the specific resource instance
  • [access_token] is an OAuth bearer token obtained via the Client Credentials flow sent in the HTTP Authorization header
Example read request 

GET https://api-developerportal.healthpartners.com/interop/external/fhir/Practitioner/12345
Authorization: Bearer [access_token]
Example response 
{
  "resourceType": "Practitioner",
  "id": "12345",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Practitioner|1.1.0"
    ]
  },
  "active": true,
  "name": [
    {
      "family": "Smith",
      "given": [
        "James"
      ],
      "suffix": [
        "MD"
      ]
    }
  ],
  "gender": "male"
}
 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., Practitioner, Organization, etc.)
  • [parameters] are the search parameters used to filter results, in the format of key=value pairs (e.g., ?name=Smith&gender=female)
  • [access_token] is an OAuth bearer token obtained via the Client Credentials flow sent in the HTTP Authorization header
Example search request 

GET https://api-developerportal.healthpartners.com/interop/external/fhir/Practitioner?name=Smith
Authorization: Bearer [access_token]
Example response 
{
  "resourceType": "Bundle",
  "entry": [
    {
      "resource": {
        "resourceType": "Practitioner",
        "id": "12345",
        "meta": {
          "profile": [
            "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Practitioner|1.1.0"
          ]
        },
        "active": true,
        "name": [
          {
            "family": "Smith",
            "given": [
              "James"
            ],
            "suffix": [
              "MD"
            ]
          }
        ],
        "gender": "male"
      }
    },
    {
      "resource": {
        "resourceType": "Practitioner",
        "id": "54321",
        "meta": {
          "profile": [
            "http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Practitioner|1.1.0"
          ]
        },
        "active": true,
        "name": [
          {
            "family": "Smith",
            "given": [
              "Jane"
            ],
            "suffix": [
              "MD"
            ]
          }
        ],
        "gender": "female"
      }
    }
  ]
}
 Implementation Guides

The following Implementation Guides (IGs) are used to implement the HealthPartners Provider Directory 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 Provider Directory API implements version 6 of the US Core IG.

DaVinci PDex Plan Net

The DaVinci PDex Plan Net IG defines a FHIR interface to health insurance plan data, associated networks and the organizations and providers in these networks.

Helpful links CMS-9115-F: Interoperability and Patient Access Final Rule HL7 FHIR Release 4 US Core Implementation Guide DaVinci PDex Plan Net Implementation Guide