SPEAR API Docs

NPI API

An NPI (National Provider Identifier) record and related records contains information obtained from NPPES describing individual medical providers. This data is separated into two types, Individual (type 1) and Organization (type 2).

These two example NPIs are representative of data found in all other NPI records.

/singular-page/npi/<int:npi_number>/dashboard/: NPI Dashboard

Retrieves comprehensive NPPES information for a specific NPI number.

Note: Only organizations (NPI type 2) have authorized official information in the "authorized_official_info" field.

Example Response - Individual

{
    "overview": {
        "name": "RICHARD RAYMOND HEIMANN M.D.",
        "npi_number": 1740296284,
        "entity_type_code": "1",
        "last_update_date": "2008-05-05",
        "certification_date": null,
        "enumeration_date": "2006-08-01",
        "is_sole_proprietor": "Y",
        "status": "Active"
    },
    "investigation": null,
    "authorized_official_info": null,
    "record_names": [
        {
            "id": 5491986,
            "name": "RICHARD RAYMOND HEIMANN, M.D.",
            "decoded_name_type_code": "Other/Unknown"
        }
    ],
    "taxonomies": [
        {
            "id": 903397,
            "seq": 1,
            "primary_switch": "Y",
            "taxonomy_code": "207L00000X",
            "license_number": "G42889",
            "license_number_state_code": "CA",
            "taxonomy_group": null
        }
    ],
    "addresses": []
}

Example Response - Organization

{
    "overview": {
        "name": "FMR INTERVENTIONAL QUALITY PAIN MANAGEMENT, A PROFESSIONAL CORP",
        "npi_number": 1568958171,
        "entity_type_code": "2",
        "last_update_date": "2023-07-28",
        "certification_date": "2023-07-28",
        "enumeration_date": "2018-07-06",
        "is_sole_proprietor": null,
        "status": "Active"
    },
    "investigation": null,
    "authorized_official_info": {
        "id": 17831105,
        "name": "F. MARINA RUSSMAN MD",
        "title_or_position": "MEDICAL DIRECTOR/OWNER",
        "telephone_number": "3102949027"
    },
    "record_names": [],
    "taxonomies": [
        {
            "id": 16458099,
            "seq": 1,
            "primary_switch": "N",
            "taxonomy_code": "111N00000X",
            "license_number": null,
            "license_number_state_code": null,
            "taxonomy_group": "193200000X MULTI-SPECIALTY GROUP"
        },
        {
            "id": 16458101,
            "seq": 2,
            "primary_switch": "N",
            "taxonomy_code": "171100000X",
            "license_number": null,
            "license_number_state_code": null,
            "taxonomy_group": "193200000X MULTI-SPECIALTY GROUP"
        },
        {
            "id": 16458100,
            "seq": 3,
            "primary_switch": "Y",
            "taxonomy_code": "208VP0000X",
            "license_number": null,
            "license_number_state_code": null,
            "taxonomy_group": "193200000X MULTI-SPECIALTY GROUP"
        }
    ],
    "addresses": [
        {
            "id": 26129610,
            "seq": 1,
            "address_type_code": 1,
            "first_line": "12415 NORWALK BLVD",
            "second_line": "UNIT 59600",
            "city": "NORWALK",
            "state": "CA",
            "postal_code": "90652",
            "country_code": "US",
            "phone": "3102949027",
            "phone_ext": null,
            "fax": "5624533059"
        },
        {
            "id": 26129609,
            "seq": 2,
            "address_type_code": 2,
            "first_line": "20620 LEAPWOOD AVE",
            "second_line": "SUITE H",
            "city": "CARSON",
            "state": "CA",
            "postal_code": "90746",
            "country_code": "US",
            "phone": "3102949027",
            "phone_ext": null,
            "fax": "5624533059"
        },
        {
            "id": 26129613,
            "seq": 1001,
            "address_type_code": 3,
            "first_line": "12115 Paramount Blvd",
            "second_line": null,
            "city": "Downey",
            "state": "CA",
            "postal_code": "902422309",
            "country_code": "US",
            "phone": "5622422070",
            "phone_ext": null,
            "fax": "5622422072"
        },
        {
            "id": 26129611,
            "seq": 1002,
            "address_type_code": 3,
            "first_line": "14925 Burbank Blvd",
            "second_line": null,
            "city": "Sherman Oaks",
            "state": "CA",
            "postal_code": "914113610",
            "country_code": "US",
            "phone": "3102949027",
            "phone_ext": null,
            "fax": "5624533059"
        },
        {
            "id": 26129612,
            "seq": 1003,
            "address_type_code": 3,
            "first_line": "1900 W Garvey Ave S Ste 223",
            "second_line": null,
            "city": "West Covina",
            "state": "CA",
            "postal_code": "917902653",
            "country_code": "US",
            "phone": "3102949027",
            "phone_ext": null,
            "fax": "5624533059"
        }
    ]
}

/npi/provider/<int:npi_number>/addresses/: NPI Addresses

Manage addresses for an NPI provider. This API supports Create, Update, and Delete operations via ModelViewSet APIs.

Note: This API does not support listing. To view addresses, use the addresses field in the NPI Dashboard API response.

Example Objects

{
    "id": 26129610,
    "seq": 1,
    "address_type_code": 1,
    "first_line": "12415 NORWALK BLVD",
    "second_line": "UNIT 59600",
    "city": "NORWALK",
    "state": "CA",
    "postal_code": "90652",
    "country_code": "US",
    "phone": "3102949027",
    "phone_ext": null,
    "fax": "5624533059"
}

Field Descriptions

Field Type Description
id integer Unique identifier for the address
seq integer Sequence number for the address (auto-generated on create)
address_type_code integer Address type: 1=Mailing, 2=Practice Location, 3=Additional
first_line string First line of the address
second_line string Second line of the address (nullable)
city string City
state string State code
postal_code string Postal/ZIP code
country_code string Country code (e.g., "US")
phone string Telephone number
phone_ext string Phone extension (nullable)
fax string Fax number (nullable)

/npi/provider/<int:npi_number>/taxonomies/: NPI Taxonomies

Manage taxonomy codes for an NPI provider. This API supports Create, Update, and Delete operations via ModelViewSet APIs.

Note: This API does not support listing. To view taxonomies, use the taxonomies field in the NPI Dashboard API response.

Example Objects

{
    "id": 903397,
    "seq": 1,
    "primary_switch": "Y",
    "taxonomy_code": "207L00000X",
    "license_number": "G42889",
    "license_number_state_code": "CA",
    "taxonomy_group": null
}

Field Descriptions

Field Type Description
id integer Unique identifier for the taxonomy
seq integer Sequence number for the taxonomy (auto-generated on create)
primary_switch string Primary taxonomy indicator ("Y" or "N")
taxonomy_code string Healthcare Provider Taxonomy Code
license_number string Provider license number (nullable)
license_number_state_code string State code for the license (nullable)
taxonomy_group string Healthcare Provider Taxonomy Group (nullable)

/singular-page/npi/type-1/<int:npi_number>/24j-association/clinic-info/: Type-1 Clinic Info

Retrieves clinic associations for a Type-1 (Individual) NPI. Shows all clinics (Type-2 NPIs) where this physician has worked, along with other physicians at those clinics.

Example Response

[
    {
        "npi_2": 1568958171,
        "npi_2_name": "FMR INTERVENTIONAL QUALITY PAIN MANAGEMENT, A PROFESSIONAL CORP",
        "physicians": [
            {
                "npi_1": 1740296284,
                "npi_1_name": "RICHARD RAYMOND HEIMANN",
                "status": "Active",
                "flagged": null,
                "licenses": [
                    {
                        "taxonomy": "207L00000X",
                        "license_number": "G42889",
                        "license_state": "CA",
                        "license_status": ""
                    }
                ]
            }
        ]
    }
]

/singular-page/npi/type-1/<int:npi_number>/24j-association/hcfa-info/: Type-1 HCFA Info

Lists HCFA billing form data associated with a Type-1 (Individual) NPI from boxes 25, 31, 32, and 33.

Example Response

[
    {
        "npi_or_tin": 954738291,
        "box": "Box 25 & 31",
        "name": "RICHARD RAYMOND HEIMANN M.D.",
        "address_line": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null
    },
    {
        "npi_or_tin": 1568958171,
        "box": "Box 32",
        "name": "FMR INTERVENTIONAL QUALITY PAIN MANAGEMENT",
        "address_line": "12415 NORWALK BLVD",
        "address_city": "NORWALK",
        "address_state": "CA",
        "address_zip": "90652"
    }
]

/singular-page/npi/type-2/<int:npi_number>/24j-association/box25/: Type-2 Box 25 Info

Lists Tax Identification Numbers (TINs) and provider names from Box 25 of HCFA forms for a Type-2 (Organization) NPI.

Example Response

[
    {
        "tin": "954738291",
        "name": "MEDICAL CLINIC INC",
        "last_billed": "2025-12-15"
    }
]

/singular-page/npi/type-2/<int:npi_number>/24j-association/box24j/: Type-2 Box 24J Info

Lists rendering provider NPIs from Box 24J of HCFA forms for a Type-2 (Organization) NPI.

Example Response

[
    {
        "npi": 1740296284,
        "name": "RICHARD RAYMOND HEIMANN",
        "last_billed": "2025-12-15"
    }
]

/singular-page/npi/type-2/<int:npi_number>/24j-association/box32/: Type-2 Box 32 Info

Lists service facility information from Box 32 of HCFA forms for a Type-2 (Organization) NPI.

Example Response

[
    {
        "name": "FMR INTERVENTIONAL QUALITY PAIN MANAGEMENT",
        "address_line": "12415 NORWALK BLVD",
        "city": "NORWALK",
        "state": "CA",
        "zip": "90652",
        "last_billed": "2025-12-15"
    }
]

/singular-page/npi/type-2/<int:npi_number>/24j-association/box33/: Type-2 Box 33 Info

Lists billing provider information from Box 33 of HCFA forms for a Type-2 (Organization) NPI.

Example Response

[
    {
        "npi": "1568958171",
        "name": "FMR INTERVENTIONAL QUALITY PAIN MANAGEMENT",
        "address_line": "12415 NORWALK BLVD",
        "city": "NORWALK",
        "state": "CA",
        "zip": "90652",
        "last_billed": "2025-12-15"
    }
]

/singular-page/npi/<int:npi_number>/cpt-list/: CPT Code List

Lists all CPT (Current Procedural Terminology) codes billed by the specified NPI with claim details.

Example Response

[
    {
        "claim_number": "CLM123456",
        "date_from": "2025-01-15",
        "date_to": "2025-01-15",
        "cpt_code": "99213",
        "cpt_description": "Office visit, established patient",
        "charge": "150.00"
    }
]

/singular-page/npi/<int:npi_number>/cpt-analysis/: CPT Code Analysis

Provides statistical analysis of CPT code usage for the specified NPI, including frequency and total charges.

Example Response

[
    {
        "cpt_code": "99213",
        "cpt_description": "Office visit, established patient",
        "percentage_used": "15.50%",
        "total_charge": "15000.00"
    },
    {
        "cpt_code": "99214",
        "cpt_description": "Office visit, established patient, moderate complexity",
        "percentage_used": "12.25%",
        "total_charge": "18000.00"
    }
]

/singular-page/npi/<int:npi_number>/referring-physician/: Referring Physicians

Lists physicians who have referred patients to the specified NPI, along with referral counts.

Example Response

[
    {
        "npi": 1234567890,
        "name": "JANE DOE MD",
        "times_referred": 45
    },
    {
        "npi": 9876543210,
        "name": "JOHN SMITH DO",
        "times_referred": 32
    }
]