Doctor

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/findadoctor-si/json-schema/findadoctor-si-doctor-schema.json",
  "title": "Doctor",
  "description": "Evidence for one doctor. found is false when the doctor_id or NPI is unknown (HTTP 404).",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/findadoctor-si-openapi.json#/components/schemas/Doctor",
  "type": "object",
  "properties": {
    "provider": {
      "$ref": "#/$defs/Provider"
    },
    "found": {
      "type": "boolean"
    },
    "doctor_id": {
      "type": "string",
      "pattern": "^dr_[0-9a-z]{12}$"
    },
    "daily_doctor_limit": {
      "$ref": "#/$defs/DailyLimit"
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "read first: e.g. opted out of Medicare, excluded from federal programs, probably not a physician"
    },
    "non_physician": {
      "type": "string",
      "description": "present when the NPI record is probably not a physician (e.g. nurse practitioner)"
    },
    "childrens_hospital_doctor": {
      "type": "string",
      "description": "present when listed on a children's hospital's own website although the registered specialty is an adult one"
    },
    "npi": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "degree": {
      "type": "string"
    },
    "gender": {
      "type": "string"
    },
    "specialty": {
      "type": "string"
    },
    "registered_specialty": {
      "type": "object",
      "properties": {
        "npi_taxonomy": {
          "type": "string"
        },
        "cms_specialty": {
          "type": "string"
        },
        "cms_secondary_specialties": {
          "type": "string"
        },
        "specialty_matched_by": {
          "type": "string"
        }
      }
    },
    "phone": {
      "type": "string"
    },
    "phone_source": {
      "type": "string",
      "description": "where the phone number comes from and its date"
    },
    "phone_address": {
      "type": "string"
    },
    "phone_note": {
      "type": "string"
    },
    "contact_note": {
      "type": "string"
    },
    "accepting_new_patients": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "what the doctor's hospital website said; confirm with the office"
    },
    "accepting_new_patients_source": {
      "type": "string"
    },
    "practice_locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "phone_note": {
            "type": "string"
          },
          "direct_phone_npi_registry": {
            "type": "string"
          }
        }
      }
    },
    "old_npi_registry_address": {
      "type": "object",
      "properties": {
        "address": {
          "type": "string"
        },
        "phone": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      },
      "description": "the NPI registry's self-reported address when it is more than 60 miles from every current CMS address and not updated for over a year: probably out of date and not used for location searches"
    },
    "medical_school": {
      "type": "string"
    },
    "graduation_year": {
      "type": "string"
    },
    "telehealth_cms": {
      "type": "boolean"
    },
    "groups_cms": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "hospitals_cms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "cms_star": {
            "type": "integer"
          }
        }
      }
    },
    "medicare_2024": {
      "type": "object",
      "properties": {
        "patients": {
          "type": "integer"
        },
        "avg_patient_age": {
          "type": "integer"
        },
        "billed_as": {
          "type": "string"
        },
        "patient_mix_high_vs_peers": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "signature_procedures_2024": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "procedure_id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "medicare_patient_days": {
            "type": "integer"
          },
          "national_rank": {
            "type": "integer"
          },
          "national_of": {
            "type": "integer"
          },
          "top_pct": {
            "type": "number"
          },
          "state": {
            "type": "string"
          },
          "state_rank": {
            "type": "integer"
          },
          "state_of": {
            "type": "integer"
          },
          "national_median": {
            "type": "number"
          }
        }
      },
      "description": "Medicare 2024 procedure volumes with national and state ranks"
    },
    "signature_procedures_note": {
      "type": "string",
      "description": "present when signature_procedures_2024 is empty: whether CMS hid counts under 11 patients or the doctor has no 2024 Medicare fee-for-service record (unknown, not zero)"
    },
    "prescribing_2024": {
      "type": [
        "object",
        "string"
      ],
      "description": "Medicare Part D 2024 summary; a sentence when there is no record"
    },
    "prescribing_signals_2024": {
      "type": "object",
      "description": "medicine groups this doctor prescribes clearly more than peers (Part D 2024)"
    },
    "industry_payments": {
      "type": [
        "object",
        "string"
      ],
      "description": "Open Payments summary; a sentence when none were reported"
    },
    "industry_research_as_principal_investigator": {
      "type": "object",
      "description": "industry-sponsored research led by this doctor (Open Payments)"
    },
    "mips_2024": {
      "type": "object",
      "description": "CMS quality program (MIPS) 2024 score"
    },
    "license_state": {
      "type": "string"
    },
    "record_status": {
      "type": "string"
    },
    "npi_registry_last_updated": {
      "type": "string"
    },
    "npi_enumerated": {
      "type": "string"
    },
    "oig_exclusion": {
      "type": [
        "object",
        "null"
      ],
      "description": "present when excluded from federal health programs"
    },
    "medicare_opt_out": {
      "type": [
        "object",
        "null"
      ],
      "description": "present when the doctor opted out of Medicare"
    },
    "hospital_websites": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "checked": {
            "type": "string",
            "description": "date the page was read"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name_on_page": {
            "type": "string"
          },
          "matched_by": {
            "type": "string",
            "description": "how the page was matched to this doctor"
          },
          "specialties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "education": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "certifications": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "accepting_new_patients": {
            "type": "boolean"
          },
          "languages_note": {
            "type": "string"
          },
          "focus_mesh": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "mesh": {
                  "type": "string",
                  "description": "standard medical term (MeSH)"
                },
                "from": {
                  "type": "string",
                  "enum": [
                    "listed",
                    "listed_general",
                    "statement"
                  ],
                  "description": "listed = the page's focus list; listed_general = general wording on that list; statement = the doctor's own profile text (counts 0.75)"
                }
              }
            },
            "description": "focus areas on the page, as MeSH terms (open urls for the page's own words)"
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "office phones on the page"
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "street": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "zip": {
                  "type": "string"
                }
              }
            },
            "description": "office addresses on the page (street may be empty)"
          },
          "insurance_listed": {
            "type": "object",
            "properties": {
              "checked": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "items_listed": {
                "type": "integer"
              },
              "by_insurer": {
                "type": "object"
              },
              "other": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "note": {
                "type": "string"
              }
            },
            "description": "insurers the hospital website listed on that date: a lead, call to confirm"
          }
        }
      },
      "description": "facts read from the doctor's hospital website"
    },
    "hospital_profile": {
      "type": "object",
      "properties": {
        "pilot": {
          "type": "string",
          "description": "which early check this comes from"
        },
        "status": {
          "type": "string"
        },
        "note": {
          "type": "string"
        },
        "trainee": {
          "type": "boolean"
        },
        "sources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "site": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          }
        },
        "focus_mesh": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "phrase": {
                "type": "string",
                "description": "same as mesh_term in this edition"
              },
              "mesh_term": {
                "type": "string"
              },
              "from": {
                "type": "string"
              },
              "site": {
                "type": "string"
              }
            }
          }
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "phone": {
          "type": [
            "string",
            "null"
          ]
        },
        "phones_on_pages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "site": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              },
              "office": {
                "type": "string"
              }
            }
          }
        },
        "departments_and_programs": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "pages_no_longer_exist": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "pages_no_longer_exist_note": {
          "type": "string"
        },
        "insurance_memorial_hermann": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "insurance_note": {
          "type": "string"
        }
      },
      "description": "Houston pediatric endocrinology only (an early check of hospital websites, 2026-10-08); hospital_websites has the wider read"
    },
    "caveats": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "read before answering"
    },
    "not_collected": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "more": {
      "type": "string"
    },
    "record": {
      "type": "object",
      "description": "detail=full only: the official record as read from NPPES and CMS"
    },
    "official_extras": {
      "type": "object",
      "description": "detail=full only: full prescribing, payments and MIPS data"
    },
    "database_caveats": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "detail=full only"
    }
  },
  "required": [
    "found"
  ],
  "$defs": {
    "DailyLimit": {
      "type": "object",
      "properties": {
        "limit_per_day": {
          "type": "integer"
        },
        "opened_today": {
          "type": "integer"
        },
        "left_today": {
          "type": "integer"
        },
        "left_out_of_this_reply": {
          "type": "integer"
        },
        "message": {
          "type": "string"
        }
      },
      "description": "Present when the daily doctor limit is near or reached for this caller."
    },
    "Provider": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "data_version": {
          "type": "string",
          "description": "database version, e.g. public-2026-10-12.2"
        }
      }
    }
  }
}