Connectivity Intelligence API

Find FHIR endpoints, Direct addresses, and other connectivity options for healthcare providers by NPI.

Overview

The Connectivity Intelligence API answers a fundamental question in health IT: "How do I connect to this provider's system?"

Given a provider's NPI, the API returns all known connectivity targets (health systems, facilities, HIEs) associated with that provider, along with their FHIR endpoints, Direct addresses, and verification evidence. Data is sourced from:

CMS NPPES endpoint reference files (updated weekly)
ONC Lantern CHPL endpoint data (70,000+ FHIR endpoints)
Hourly verification probes that test endpoint availability and extract SMART/OAuth metadata

Currently, connectivity data is richest for organization NPIs (Type 2). Individual provider NPIs return connectivity targets only when the provider is linked to a known organization. If no links exist, the response will contain an empty connectivity_targets array.

Endpoints

Method	Path	Description
GET	`/v1/npi/:npi/connectivity`	Look up connectivity options for a provider

Lookup

Find connectivity options for a provider

Request

Node.js

import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

const result = await client.connectivity.lookup("1234567890");
console.log(result.provider_summary.name);
console.log(result.connectivity_targets);

Response

JSON

{
  "npi": "1234567890",
  "provider_summary": {
    "name": "ACME HEALTH PARTNERS",
    "entity_type": "organization",
    "primary_taxonomy": "207Q00000X",
    "primary_taxonomy_desc": "Family Medicine"
  },
  "connectivity_targets": [
    {
      "target_id": "target_acme_health",
      "name": "Acme Health System",
      "type": "health_system",
      "link_type": "organization_npi",
      "link_confidence": "high",
      "ehr_vendor": "Epic",
      "network_participation": [
        "Carequality",
        "CommonWell"
      ],
      "endpoints": [
        {
          "endpoint_id": "ep_fhir_acme_001",
          "type": "fhir_r4",
          "url": "https://fhir.acmehealth.example.org/api/FHIR/R4",
          "scope": "production",
          "status": "active",
          "last_verified_at": "2026-02-10T08:15:00Z",
          "fhir_metadata": {
            "version": "4.0.1",
            "capabilities": [
              "launch-ehr",
              "launch-standalone",
              "patient-access"
            ],
            "supported_resources": [
              "Patient",
              "Condition",
              "MedicationRequest",
              "AllergyIntolerance"
            ],
            "security": {
              "oauth_authorize_url": "https://fhir.acmehealth.example.org/oauth2/authorize",
              "oauth_token_url": "https://fhir.acmehealth.example.org/oauth2/token"
            }
          },
          "availability": {
            "percentage": 99.8,
            "probe_count": 142,
            "last_checked": "2026-02-10T08:15:00Z",
            "last_successful": "2026-02-10T08:15:00Z",
            "consecutive_failures": 0
          },
          "evidence_summary": {
            "latest_verification": "http_probe",
            "verification_count": 142,
            "first_seen": "2026-01-15T00:00:00Z",
            "sources": [
              "http_probe",
              "smart_discovery",
              "nppes_endpoint_file"
            ]
          }
        },
        {
          "endpoint_id": "ep_direct_acme_001",
          "type": "direct",
          "url": "provider@direct.acmehealth.example.org",
          "scope": "production",
          "status": "active",
          "last_verified_at": "2026-02-09T14:30:00Z",
          "evidence_summary": {
            "latest_verification": "nppes_endpoint_file",
            "verification_count": 4,
            "first_seen": "2026-01-20T00:00:00Z",
            "sources": [
              "nppes_endpoint_file"
            ]
          }
        }
      ]
    }
  ],
  "meta": {
    "data_as_of": "2026-02-10T08:15:00Z",
    "disclaimer": "Connectivity data is provided as-is. Verify endpoint access with each organization before use in production."
  }
}

Response Structure

`provider_summary`

Basic information about the provider from the NPI registry.

Field	Type	Description
`name`	string	Provider name (individual or organization)
`entity_type`	string	`"individual"`, `"organization"`, or `"unknown"`
`primary_taxonomy`	string	Primary NUCC taxonomy code
`primary_taxonomy_desc`	string	Taxonomy description (e.g., "Family Medicine")

`connectivity_targets[]`

Organizations linked to this NPI with their available endpoints.

Field	Type	Description
`target_id`	string	Unique identifier for the organization
`name`	string	Organization name
`type`	string	Organization type (see Target Types)
`link_type`	string	How the NPI is linked (see Link Types)
`link_confidence`	string	Confidence level (see Confidence Levels)
`ehr_vendor`	string?	EHR vendor name (e.g., "Epic", "Oracle Health")
`network_participation`	string[]?	Health information networks (e.g., "Carequality", "CommonWell")
`endpoints`	array	Available endpoints for this target

`endpoints[]`

Individual connectivity endpoints within a target.

Field	Type	Description
`endpoint_id`	string	Unique endpoint identifier
`type`	string	Endpoint type (see Endpoint Types)
`url`	string	Base URL or Direct address
`scope`	string	`"production"`, `"sandbox"`, or `"unknown"`
`status`	string	Current status (see Endpoint Statuses)
`last_verified_at`	string?	ISO 8601 timestamp of last verification
`fhir_metadata`	object?	FHIR-specific metadata (version, capabilities, OAuth URLs)
`availability`	object?	Uptime statistics from automated probing
`evidence_summary`	object	Summary of verification evidence

`availability`

Uptime statistics computed from automated hourly probing.

Field	Type	Description
`percentage`	number	Uptime percentage (e.g., 99.8)
`probe_count`	number	Total number of probes recorded
`last_checked`	string	When the endpoint was last probed
`last_successful`	string \| null	When the endpoint last responded successfully
`consecutive_failures`	number	Current streak of consecutive failures

`fhir_metadata`

Metadata extracted from FHIR endpoint probing (FHIR endpoints only).

Field	Type	Description
`version`	string?	FHIR version (e.g., "4.0.1")
`capabilities`	string[]?	SMART launch capabilities
`supported_resources`	string[]?	FHIR resource types supported
`security.oauth_authorize_url`	string?	OAuth2 authorization URL
`security.oauth_token_url`	string?	OAuth2 token URL

Enums

Endpoint Types

Type	Description
`fhir_r4`	FHIR R4 server
`fhir_stu3`	FHIR STU3 server
`fhir_dstu2`	FHIR DSTU2 server
`direct`	Direct Messaging address
`hl7v2_adt`	HL7v2 ADT feed
`x12`	X12 EDI endpoint
`other`	Other endpoint type

Endpoint Statuses

Status	Description
`active`	Endpoint responded successfully on last verification
`inactive`	Endpoint is known to be offline or decommissioned
`unverified`	Endpoint has not yet been verified
`unreachable`	Endpoint failed to respond on last verification

Target Types

Type	Description
`health_system`	Integrated health system or hospital network
`facility`	Individual hospital or clinic
`practice`	Medical practice or physician group
`hie`	Health Information Exchange
`qhin`	Qualified Health Information Network (TEFCA)
`payer`	Health insurance payer

Link Types

Type	Description
`organization_npi`	This NPI belongs to the organization itself
`employed_by`	Provider is employed by this organization
`affiliated`	Provider has privileges or affiliation
`practice_location`	Provider practices at this location

Confidence Levels

Level	Description
`high`	Direct match (e.g., organization NPI, NPPES endpoint file)
`medium`	Strong indirect evidence (e.g., normalized name match)
`low`	Weak indirect evidence
`inferred`	Algorithmically inferred link

SDK Usage