{
  "openapi": "3.1.0",
  "info": {
    "title": "PE or Not? API",
    "version": "0.1.0",
    "description": "Is a dentist, eye doctor, vet, dermatology or GI practice private-equity (PE) backed? Free, read-only, no key. Every response has a ready-to-use \"say\" sentence, sources, coverage and wording rules. Wording: say \"PE-backed\" or \"affiliated with a PE-backed group\" (never \"owned by\" a PE firm for dental or eye care), \"no known PE ties\" (never \"independent\"), \"Not confirmed\" for label unconfirmed; cite sources; never say a practice is worse because of its owner. Published by TechCrowds, LLC. Docs: https://peornot.org/developers/",
    "contact": {
      "url": "https://peornot.org/developers/"
    }
  },
  "servers": [
    {
      "url": "https://peornot.org"
    }
  ],
  "paths": {
    "/api/lookup/": {
      "get": {
        "operationId": "lookupBusiness",
        "summary": "Is this business PE-backed?",
        "description": "Check one business. Give name plus city and state or ZIP; street address or phone makes it surer. Answer with the \"say\" text and cite sources. On possible_matches or multiple_matches ask the user for the address.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Business name, e.g. Aspen Dental."
          },
          {
            "name": "address",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Street address or full address."
          },
          {
            "name": "street",
            "in": "query",
            "required": false,
            "description": "Street address only, e.g. '4949 Hedgcoxe Rd Ste 160' (alternative to address).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Two-letter code or state name."
          },
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "5-digit ZIP."
          },
          {
            "name": "phone",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "industry",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "dental",
                "eye",
                "vet",
                "derm",
                "gi"
              ]
            },
            "description": "Leave out to infer from the name."
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/search/": {
      "get": {
        "operationId": "findBusinesses",
        "summary": "Find businesses in an area by ownership label",
        "description": "List practices in a ZIP, city or state, filtered by label (e.g. no_known_pe_ties). Dental and eye care cover every NPI-registered practice; vet, derm and GI only the tracked groups' locations.",
        "parameters": [
          {
            "name": "industry",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "dental",
                "eye",
                "vet",
                "derm",
                "gi"
              ],
              "default": "dental"
            }
          },
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "label",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated: pe_backed, lender_owned, corporate_owned, health_system_owned, group_practice, vc_backed, no_known_pe_ties, unconfirmed, not_labeled (aliases: pe, no_pe)."
          },
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only names containing these words."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Practices in the area",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/group/": {
      "get": {
        "operationId": "getGroup",
        "summary": "Who owns or backs this group?",
        "description": "An owner group or brand: label, owner or PE backers, since when, PE stake, deal model, sources with headlines, known locations by state.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Group id, e.g. dental:heartland-dental."
          },
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Group or brand name."
          },
          {
            "name": "industry",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "dental",
                "eye",
                "vet",
                "derm",
                "gi"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Group details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Common": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "say": {
            "type": "string",
            "description": "The sentence to use in the answer."
          },
          "coverage": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "level": {
                "type": "string",
                "enum": [
                  "deep_metro",
                  "national_npi",
                  "chains_only"
                ]
              },
              "note": {
                "type": "string"
              }
            }
          },
          "wording_rules": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "data_as_of": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          }
        }
      },
      "Source": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "headline": {
            "type": "string"
          },
          "site": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "evidence": {
            "type": "string"
          }
        }
      },
      "Match": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "industry": {
            "type": "string"
          },
          "label": {
            "type": "string",
            "enum": [
              "pe_backed",
              "lender_owned",
              "corporate_owned",
              "health_system_owned",
              "group_practice",
              "vc_backed",
              "no_known_pe_ties",
              "unconfirmed",
              "not_labeled"
            ]
          },
          "label_text": {
            "type": "string"
          },
          "say": {
            "type": "string"
          },
          "owner_group": {
            "type": [
              "object",
              "null"
            ]
          },
          "deal_depth": {
            "type": [
              "object",
              "null"
            ]
          },
          "confidence": {
            "type": [
              "string",
              "null"
            ]
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "match": {
            "type": "object",
            "properties": {
              "how": {
                "type": "string"
              },
              "certainty": {
                "type": "string"
              }
            }
          },
          "page_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "correction_url": {
            "type": "string"
          }
        }
      },
      "LookupResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Common"
          },
          {
            "type": "object",
            "properties": {
              "matches": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Match"
                }
              }
            }
          }
        ]
      },
      "SearchResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Common"
          },
          {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "returned": {
                "type": "integer"
              },
              "next_offset": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "counts_by_label": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              },
              "results": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          }
        ]
      },
      "GroupResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Common"
          },
          {
            "type": "object",
            "properties": {
              "group": {
                "type": "object"
              },
              "other_matches": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}