resolve_provider

What it answers

1. 1Resolve a provider's identity: an NPI, an EIN, or an organisation name (+ state) -> the Medicare CCN(s) it maps to, the CCN's provider type from the CCN authority (vlada_curated.dim_provider_ccn: 101,528 CCNs across hospitals, SNFs, home health, hospice, FQHC, RHC, ASC, dialysis, IRF, LTCH), the NPPES record, the PECOS Medicare enrollment(s) with organisation name and provider type, and (include_ownership, default true) the PECOS ownership edges — owners, percentage, and the private-equity / REIT / holding-company / chain flags.
2. 2Every candidate carries its match method, a confidence, and the source table per field.
3. 3NPI->CCN is resolved by AGREEMENT across two bridges (provider_facility_xref, dim_hospital_external); if they disagree the answer is ambiguous_conflict with both candidates and no resolved CCN, never a guess.
4. 4An unknown NPI returns unresolved with the reason, not an error.
5. 5EIN and name resolution reach hospitals only (the estate's EIN-bearing roster); a shared-system EIN lists every CCN as a candidate.
6. 6Each candidate carries ccn, npi, hospital_name and health_system at its top level; resolution carries resolved_npi and resolved_health_system; repeated PECOS rows are collapsed to one per enrollment.

Inputs (5)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
resolve_provider(npi="1477902641", include_ownership=true)

curl -X POST https://api.vladahealth.com/v1/tools/resolve_provider \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"npi":"1477902641","include_ownership":true}'

# the schema, no key
curl https://api.vladahealth.com/v1/tools/resolve_provider/schema

A real answer

{
 "value": {
  "found": true,
  "not_found_reason": null,
  "query": {
   "npi": "1477902641",
   "ein": null,
   "name": null,
   "state": null,
   "include_ownership": true
  },
  "resolution": {
   "status": "resolved",
   "resolved_ccn": "070005",
   "resolved_npi": "1477902641",
   "resolved_health_system": "Prospect Medical Holdings",
   "confidence": 0.9,
   "key_type": "npi"
  },
  "candidates": [
   {
    "ccn": "070005",
    "npi": "1477902641",
    "hospital_name": null,
    "city": null,
    "state_code": null,
    "health_system": "Prospect Medical Holdings",
    "health_system_id": "HSI00000851",
    "shares_npi_with_ccns": [],
    "provider_type": "hospital",
    "all_provider_types": "hospital",
    "provider_type_count": 1,
    "in_ccn_authority": true,
    "confidence": 0.9,
    "sources": []
   }
  ],
  "nppes": {
   "npi": "1477902641",
   "entity_type": "2",
   "name": "PROSPECT WATERBURY, INC.",
   "first_name": null,
   "last_name": null,
   "credential": null,
   "city": "WATERBURY",
   "state": "CT",
   "postal_code": "067082613",
   "taxonomy": "282N00000X"
  },
  "pecos_enrollments": [
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": null,
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2018-12-31"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": null,
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2017-10-30"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2023-03-31"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": "N",
    "asserted_at": "2026-06-28"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": null,
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2020-12-31"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2021-10-05"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": null,
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2019-10-01"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2022-09-30"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": "N",
    "asserted_at": "2025-10-01"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2024-10-07"
   },
   {
    "enrollment_id": "O20160730000005",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": "N",
    "asserted_at": "2026-07-01"
   },
   {
    "enrollment_id": "O20160929001327",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2024-10-07"
   },
   {
    "enrollment_id": "O20160929001327",
    "associate_id": "4688967581",
    "org_name": "PROSPECT WATERBURY INC",
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2023-03-31"
   },
   {
    "enrollment_id": "O20160929001327",
    "associate_id": "4688967581",
    "org_name": null,
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2020-12-31"
   },
   {
    "enrollment_id": "O20160929001327",
    "associate_id": "4688967581",
    "org_name": null,
    "individual_name": null,
    "provider_type_code": "00-09",
    "provider_type_desc": "PART A PROVIDER - HOSPITAL",
    "state": "CT",
    "multiple_npi_flag": null,
    "asserted_at": "2018-12-31"
   },
   {
    "enrollment_id": "O20160929001327",
    "associa
…

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  }
 },
 "title": "ResolveProviderResponse",
 "type": "object"
}

Sources

Known limits (4)

1. 1NPI->CCN recall ~87% (bridge union, measured 2026-06 by the employer-book harness); individual NPIs and non-hospital organisations usually resolve to PECOS + NPPES only.
2. 2EIN and name resolution reach hospitals (dim_hospital_external) plus PECOS org names; the non-hospital rosters carry no EIN.
3. 3provider_type follows the ten CMS rosters in dim_provider_ccn; a provider type we hold no roster for is absent from the authority.
4. 4Ownership edges are keyed on PECOS enrollment_id and are self-reported; percentage can be null for indirect interests.