FHIRfly
Dashboard

NPI API

Look up National Provider Identifier (NPI) information for healthcare providers.

Overview

The NPI is a unique 10-digit identification number for healthcare providers in the United States. FHIRfly provides fast lookups against the CMS NPPES database enriched with NUCC taxonomy data.

Endpoints

Method Path Description
GET /v1/npi/:npi Single NPI lookup
POST /v1/npi/_batch Batch NPI lookup (up to 100)
GET /v1/npi/shapes List available response shapes

Single Lookup

Look up a healthcare provider by NPI

Request
Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

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

const result = await client.npi.lookup("1679576722");
console.log(result.data);
Response
JSON
{
  "data": {
    "entity_type": "individual",
    "enumeration_date": "2005-05-23",
    "is_active": true,
    "last_update_date": "2007-07-08",
    "name": {
      "credential_text": "M.D.",
      "first": "DAVID",
      "last": "WIEBE",
      "middle": "A",
      "prefix": "",
      "sex": "M",
      "suffix": ""
    },
    "npi": "1679576722",
    "organization_name": null,
    "practice_address": {
      "city": "KEARNEY",
      "country": "US",
      "fax": "3088652506",
      "line1": "3500 CENTRAL AVE",
      "line2": "",
      "phone": "3088652512",
      "postal": "688472944",
      "state": "NE"
    },
    "taxonomies": [
      {
        "classification": "Orthopaedic Surgery",
        "code": "207X00000X",
        "display_name": "Orthopaedic Surgery Physician",
        "grouping": "Allopathic & Osteopathic Physicians",
        "license_number": "12637",
        "license_state": "NE",
        "primary": true,
        "specialization": null
      }
    ]
  },
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "CMS NPPES with NUCC Taxonomy. Accessed 2026-01-14 via FHIRfly.",
      "license": "public_domain",
      "source_name": "CMS NPPES with NUCC Taxonomy"
    }
  }
}

Provider Types

Type Description
individual Individual healthcare provider (Type 1)
organization Healthcare organization (Type 2)

Batch Lookup

Look up multiple NPIs in a single request (up to 100):

Look up multiple providers

Request
Node.js
import { Fhirfly } from "@fhirfly-io/terminology";

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

const result = await client.npi.lookupMany(["1679576722","1588667638","1215930367"]);
console.log(result.data.results);
Response
JSON
{
  "count": 3,
  "results": [
    {
      "input": "1679576722",
      "npi": "1679576722",
      "status": "ok",
      "data": {
        "entity_type": "individual",
        "name": {
          "first": "DAVID",
          "last": "WIEBE"
        },
        "taxonomies": [
          {
            "code": "207X00000X",
            "classification": "Orthopaedic Surgery"
          }
        ]
      }
    },
    {
      "input": "1588667638",
      "npi": "1588667638",
      "status": "ok",
      "data": {
        "entity_type": "individual",
        "name": {
          "first": "WILLIAM",
          "last": "PILCHER"
        },
        "taxonomies": [
          {
            "code": "208600000X",
            "classification": "Surgery"
          }
        ]
      }
    },
    {
      "input": "1215930367",
      "npi": "1215930367",
      "status": "ok",
      "data": {
        "entity_type": "individual",
        "name": {
          "first": "LAURENT",
          "last": "GRESSOT"
        },
        "taxonomies": [
          {
            "code": "207Q00000X",
            "classification": "Family Medicine"
          }
        ]
      }
    }
  ],
  "meta": {
    "legal": {
      "license": "public_domain"
    }
  }
}

Batch with shape=full

When using shape=full on batch requests, the response includes meta.source with provenance information:

POST /v1/npi/_batch?shape=full

{
  "count": 3,
  "results": [
    {
      "input": "1679576722",
      "npi": "1679576722",
      "status": "ok",
      "data": {
        "entity_type": "individual",
        "name": { "first": "DAVID", "last": "WIEBE" },
        "taxonomies": [{ "code": "207X00000X", "classification": "Orthopaedic Surgery" }]
      }
    }
  ],
  "meta": {
    "source": {
      "name": "CMS NPPES",
      "url": "https://npiregistry.cms.hhs.gov/",
      "version": "weekly",
      "fhirfly_updated_at": "2026-03-01T03:00:00Z"
    },
    "legal": {
      "license": "public_domain",
      "attribution_required": false
    }
  }
}

Response Shapes

Control the level of detail in responses with the shape query parameter:

Shape Description
compact Minimal data for lists and autocomplete
standard Core structured data (default)
full Complete data with provenance for AI agents 
# Minimal data
GET /v1/npi/1679576722?shape=compact

# Standard data (default)
GET /v1/npi/1679576722?shape=standard

# Full data with provenance
GET /v1/npi/1679576722?shape=full

See Response Shapes for field details.

Required Scopes

  • npi.read - Single and batch lookups