mphapi 0.4.3__py3-none-any.whl → 1.9.1__py3-none-any.whl

mphapi/claim.py

@@ -60,6 +60,9 @@ class Provider(BaseModel):
     npi: str
     """National Provider Identifier of the provider (from NM109, required)"""
 
+    ccn: Optional[str] = None
+    """CMS Certification Number (optional)"""
+
     provider_tax_id: Annotated[Optional[str], field_name("providerTaxID")] = None
     """City of the provider (from N401, highly recommended)"""
 
@@ -195,8 +198,6 @@ class Service(BaseModel):
     procedure_code: Optional[str] = None
     """Procedure code (from SV101_02 / SV202_02)"""
 
-    hipps_code: Optional[str] = None
-
     procedure_modifiers: Optional[list[str]] = None
     """Procedure modifiers (from SV101_03, 4, 5, 6 / SV202_03, 4, 5, 6)"""
 
@@ -334,12 +335,6 @@ class RateSheetService(BaseModel):
     procedure_modifiers: Optional[list[str]] = None
     """Procedure modifiers (from SV101_03, 4, 5, 6 / SV202_03, 4, 5, 6)"""
 
-    billed_amount: Optional[float] = None
-    """Billed charge for the service (from SV102 / SV203)"""
-
-    allowed_amount: Optional[float] = None
-    """Plan allowed amount for the service (non-EDI)"""
-
 
 class RateSheet(BaseModel):
     npi: str
@@ -375,14 +370,5 @@ class RateSheet(BaseModel):
     drg: Optional[str] = None
     """Diagnosis Related Group for inpatient services (from HI DR)"""
 
-    billed_amount: Optional[float] = None
-    """Billed amount from provider (from CLM02)"""
-
-    allowed_amount: Optional[float] = None
-    """Amount allowed by the plan for payment. Both member and plan responsibility (non-EDI)"""
-
-    paid_amount: Optional[float] = None
-    """Amount paid by the plan for the claim (non-EDI)"""
-
     services: Optional[list[RateSheetService]] = None
     """One or more services provided to the patient (from LX loop)"""

mphapi/client.py

@@ -1,11 +1,11 @@
 import urllib.parse
-from typing import Any, Mapping, Sequence
+from typing import Annotated, Any, Mapping, Optional, Sequence
 
 import requests
 from pydantic import BaseModel, StrictBool, TypeAdapter
 
 from .claim import Claim, RateSheet
-from .pricing import Pricing
+from .fields import camel_case_model_config, field_name
 from .response import Response, Responses
 
 Header = Mapping[str, str | bytes | None]
@@ -14,49 +14,73 @@ Header = Mapping[str, str | bytes | None]
 class PriceConfig(BaseModel):
     """PriceConfig is used to configure the behavior of the pricing API"""
 
-    price_zero_billed: StrictBool
+    model_config = camel_case_model_config
+
+    contract_ruleset: Optional[str] = None
+    """set to the name of the ruleset to use for contract pricing"""
+
+    price_zero_billed: Optional[StrictBool] = False
     """set to true to price claims with zero billed amounts (default is false)"""
 
-    is_commercial: StrictBool
-    """set to true to use commercial code crosswalks"""
+    is_commercial: Optional[StrictBool] = False
+    """set to true to crosswalk codes from commercial codes Medicare won't pay for to substitute codes they do pay for (e.g. 99201 to G0463)"""
 
-    disable_cost_based_reimbursement: StrictBool
-    """by default, the API will use cost-based reimbursement for MAC priced line-items. This is the best estimate we have for this proprietary pricing"""
+    disable_cost_based_reimbursement: Optional[StrictBool] = False
+    """set to true to disable cost-based reimbursement for line items paid as a percent of cost"""
 
-    use_commercial_synthetic_for_not_allowed: StrictBool
+    use_commercial_synthetic_for_not_allowed: Optional[StrictBool] = False
     """set to true to use a synthetic Medicare price for line-items that are not allowed by Medicare"""
 
-    use_drg_from_grouper: StrictBool
+    use_drg_from_grouper: Annotated[
+        Optional[StrictBool], field_name("useDRGFromGrouper")
+    ] = False
     """set to true to always use the DRG from the inpatient grouper"""
 
-    use_best_drg_price: StrictBool
+    use_best_drg_price: Annotated[StrictBool, field_name("useBestDRGPrice")]
     """set to true to use the best DRG price between the price on the claim and the price from the grouper"""
 
-    override_threshold: float
+    override_threshold: Optional[float] = 0
     """set to a value greater than 0 to allow the pricer flexibility to override NCCI edits and other overridable errors and return a price"""
 
-    include_edits: StrictBool
+    include_edits: Optional[StrictBool] = False
     """set to true to include edit details in the response"""
 
-    continue_on_edit_fail: StrictBool
+    continue_on_edit_fail: Optional[StrictBool] = False
     """set to true to continue to price the claim even if there are edit failures"""
 
-    continue_on_provider_match_fail: StrictBool
+    continue_on_provider_match_fail: Optional[StrictBool] = False
     """set to true to continue with a average provider for the geographic area if the provider cannot be matched"""
 
-    disable_machine_learning_estimates: StrictBool
+    disable_machine_learning_estimates: Optional[StrictBool] = False
     """set to true to disable machine learning estimates (applies to estimates only)"""
 
+    assume_impossible_anesthesia_units_are_minutes: Optional[StrictBool] = False
+    """set to true to divide impossible anesthesia units by 15 (max of 96 anesthesia units per day) (default is false)"""
+
+    fallback_to_max_anesthesia_units_per_day: Optional[StrictBool] = False
+    """set to true to fallback to the maximum anesthesia units per day (default is false which will error if there are more than 96 anesthesia units per day)"""
+
+    allow_partial_results: Optional[StrictBool] = False
+    """set to true to return partially repriced claims. This can be useful to get pricing on non-erroring line items, but should be used with caution"""
+
+
+# It may be a bit jarring to see this import not at the top of the file. This is
+# intentional as `.pricing` depends on `PriceConfig`.
+from .pricing import Pricing  # noqa: E402
+
 
 class Client:
     url: str
     headers: Header
 
-    def __init__(self, apiKey: str, isTest: bool = False):
-        if isTest:
-            self.url = "https://api-test.myprice.health"
+    def __init__(self, apiKey: str, isTest: bool = False, url: str | None = None):
+        if url is None:
+            if isTest:
+                self.url = "https://api-test.myprice.health"
+            else:
+                self.url = "https://api.myprice.health"
         else:
-            self.url = "https://api.myprice.health"
+            self.url = url
 
         self.headers = {"x-api-key": apiKey}
 
@@ -74,9 +98,7 @@ class Client:
             headers={**self.headers, **headers},
         )
 
-    def _receive_response[
-        Model: BaseModel
-    ](
+    def _receive_response[Model: BaseModel](
         self,
         path: str,
         body: BaseModel,
@@ -105,9 +127,7 @@ class Client:
             .result()
         )
 
-    def _receive_responses[
-        Model: BaseModel
-    ](
+    def _receive_responses[Model: BaseModel](
         self,
         path: str,
         body: Sequence[BaseModel],
@@ -215,7 +235,7 @@ class Client:
         if config.use_commercial_synthetic_for_not_allowed:
             headers["use-commercial-synthetic-for-not-allowed"] = "true"
 
-        if config.override_threshold > 0:
+        if config.override_threshold is not None and config.override_threshold > 0:
             headers["override-threshold"] = str(config.override_threshold)
 
         if config.include_edits:

mphapi/client_test.py

@@ -0,0 +1,38 @@
+import json
+import os
+
+# This import annoys Pylance for some reason.
+from pytest_snapshot.plugin import Snapshot  # type: ignore
+
+from . import Claim, Client, PriceConfig
+
+
+def test_client(snapshot: Snapshot):
+    api_key = os.getenv("API_KEY")
+    if api_key is None:
+        raise EnvironmentError("API_KEY must be set")
+
+    api_url = os.getenv("API_URL")
+
+    client = Client(api_key, url=api_url)
+
+    config = PriceConfig(
+        is_commercial=True,
+        disable_cost_based_reimbursement=False,
+        use_commercial_synthetic_for_not_allowed=True,
+        use_drg_from_grouper=False,
+        use_best_drg_price=True,
+        override_threshold=300,
+        include_edits=True,
+    )
+
+    tests = ["hcfa", "inpatient", "outpatient"]
+
+    for test in tests:
+        with open(f"testdata/{test}.json", "r") as f:
+            data = json.load(f)
+
+            claim = Claim.model_validate(data)
+            pricing = client.price(config, claim)
+
+            snapshot.assert_match(pricing.model_dump_json(indent=4), f"{test}.json")

mphapi/pricing.py

@@ -3,6 +3,7 @@ from typing import Annotated, Optional
 
 from pydantic import BaseModel, Field
 
+from .client import PriceConfig
 from .fields import camel_case_model_config, field_name
 from .response import ResponseError
 
@@ -143,6 +144,25 @@ class OutpatientPriceDetail(BaseModel):
     """Wage index used for geographic adjustment"""
 
 
+class AllowedRepricingFormula(BaseModel):
+    """The formula used to calculate the allowed amount"""
+
+    medicare_percent: Optional[float] = None
+    """Percentage of the Medicare amount used to calculate the allowed amount"""
+
+    billed_percent: Optional[float] = None
+    """Percentage of the billed amount used to calculate the allowed amount"""
+
+    fee_schedule: Optional[float] = None
+    """Fee schedule amount used as the allowed amount"""
+
+    fixed_amount: Optional[float] = None
+    """Fixed amount used as the allowed amount"""
+
+    per_diem: Optional[float] = None
+    """Per diem rate used to calculate the allowed amount"""
+
+
 class ProviderDetail(BaseModel):
     """
     ProviderDetail contains basic information about the provider and/or locality used for pricing.
@@ -161,6 +181,12 @@ class ProviderDetail(BaseModel):
     locality: Optional[int] = None
     """Geographic locality number used for pricing"""
 
+    geographic_cbsa: Annotated[Optional[int], field_name("geographicCBSA")] = None
+    """Core-Based Statistical Area (CBSA) number for provider ZIP"""
+
+    state_cbsa: Annotated[Optional[int], field_name("stateCBSA")] = None
+    """State Core-Based Statistical Area (CBSA) number"""
+
     rural_indicator: Optional[RuralIndicator] = None
     """Indicates whether provider is Rural (R), Super Rural (B), or Urban (blank)"""
 
@@ -224,9 +250,6 @@ class LineEdits(BaseModel):
 
     model_config = camel_case_model_config
 
-    denial_or_rejection_text: Optional[str] = None
-    """The overall explanation for why this line item was denied or rejected by the claim editor"""
-
     procedure_edits: Optional[list[str]] = None
     """Detailed description of each procedure code edit error (from outpatient editor)"""
 
@@ -251,9 +274,6 @@ class LineEdits(BaseModel):
     revenue_edits: Optional[list[str]] = None
     """Detailed description of each revenue code edit error (from outpatient editor)"""
 
-    professional_edits: Optional[list[str]] = None
-    """Detailed description of each professional claim edit error"""
-
 
 class PricedService(BaseModel):
     """PricedService contains the results of a pricing request for a single service line"""
@@ -278,12 +298,18 @@ class PricedService(BaseModel):
     medicare_repricing_note: Optional[str] = None
     """Note explaining approach for pricing or reason for error"""
 
+    network_code: Optional[str] = None
+    """Code describing the network used for allowed amount pricing"""
+
     allowed_repricing_code: Optional[LineRepricingCode] = None
     """Explains the methodology used to calculate allowed amount"""
 
     allowed_repricing_note: Optional[str] = None
     """Note explaining approach for pricing or reason for error"""
 
+    allowed_repricing_formula: Optional[AllowedRepricingFormula] = None
+    """Formula used to calculate the allowed amount"""
+
     technical_component_amount: Optional[float] = None
     """Amount Medicare would pay for the technical component"""
 
@@ -305,6 +331,30 @@ class PricedService(BaseModel):
     payment_indicator: Optional[str] = None
     """Text which explains the type of payment for Medicare"""
 
+    discount_formula: Optional[str] = None
+    """The multi-procedure discount formula used to calculate the allowed amount (outpatient only)"""
+
+    line_item_denial_or_rejection_flag: Optional[str] = None
+    """Identifies how a line item was denied or rejected and how the rejection can be overridden (outpatient only)"""
+
+    packaging_flag: Optional[str] = None
+    """Indicates if the service is packaged and the reason for packaging (outpatient only)"""
+
+    payment_adjustment_flag: Optional[str] = None
+    """Identifies special adjustments made to the payment (outpatient only)"""
+
+    payment_adjustment_flag2: Optional[str] = None
+    """Identifies special adjustments made to the payment (outpatient only)"""
+
+    payment_method_flag: Optional[str] = None
+    """The method used to calculate the allowed amount (outpatient only)"""
+
+    composite_adjustment_flag: Optional[str] = None
+    """Assists in composite APC determination (outpatient only)"""
+
+    hcpcs_apc: Annotated[Optional[str], field_name("hcpcsAPC")] = None
+    """Ambulatory Payment Classification code of the line item HCPCS (outpatient only)"""
+
     payment_apc: Annotated[Optional[str], field_name("paymentAPC")] = None
     """Ambulatory Payment Classification"""
 
@@ -332,6 +382,9 @@ class Pricing(BaseModel):
     medicare_repricing_note: Optional[str] = None
     """Note explaining approach for pricing or reason for error"""
 
+    network_code: Optional[str] = None
+    """Code describing the network used for allowed amount pricing"""
+
     allowed_repricing_code: Optional[ClaimRepricingCode] = None
     """Explains the methodology used to calculate allowed amount (CON, RBP, SCA, or IFO)"""
 
@@ -359,6 +412,9 @@ class Pricing(BaseModel):
     pricer_result: Optional[str] = None
     """Pricer return details"""
 
+    price_config: Optional[PriceConfig] = None
+    """The configuration used for pricing the claim"""
+
     services: list[PricedService] = Field(min_length=1)
     """Pricing for each service line on the claim"""
 

mphapi/snapshots/client_test/test_client/hcfa.json

@@ -0,0 +1,75 @@
+{
+    "claim_id": "1234",
+    "medicare_amount": 124.18,
+    "allowed_amount": null,
+    "medicare_repricing_code": "MED",
+    "medicare_repricing_note": null,
+    "network_code": null,
+    "allowed_repricing_code": null,
+    "allowed_repricing_note": null,
+    "medicare_std_dev": null,
+    "medicare_source": null,
+    "inpatient_price_detail": null,
+    "outpatient_price_detail": null,
+    "provider_detail": {
+        "ccn": null,
+        "mac": 4412,
+        "locality": 99,
+        "geographic_cbsa": 32580,
+        "state_cbsa": 45,
+        "rural_indicator": null,
+        "specialty_type": null,
+        "hospital_type": null
+    },
+    "edit_detail": null,
+    "pricer_result": null,
+    "price_config": {
+        "contract_ruleset": null,
+        "price_zero_billed": false,
+        "is_commercial": true,
+        "disable_cost_based_reimbursement": false,
+        "use_commercial_synthetic_for_not_allowed": true,
+        "use_drg_from_grouper": false,
+        "use_best_drg_price": true,
+        "override_threshold": 300.0,
+        "include_edits": true,
+        "continue_on_edit_fail": false,
+        "continue_on_provider_match_fail": false,
+        "disable_machine_learning_estimates": false,
+        "assume_impossible_anesthesia_units_are_minutes": false,
+        "fallback_to_max_anesthesia_units_per_day": false,
+        "allow_partial_results": false
+    },
+    "services": [
+        {
+            "line_number": "1",
+            "provider_detail": null,
+            "medicare_amount": 124.18,
+            "allowed_amount": null,
+            "medicare_repricing_code": "MED",
+            "medicare_repricing_note": null,
+            "network_code": null,
+            "allowed_repricing_code": null,
+            "allowed_repricing_note": null,
+            "allowed_repricing_formula": null,
+            "technical_component_amount": null,
+            "professional_component_amount": null,
+            "medicare_std_dev": null,
+            "medicare_source": "MPFS",
+            "pricer_result": "Processed",
+            "status_indicator": "A",
+            "payment_indicator": null,
+            "discount_formula": null,
+            "line_item_denial_or_rejection_flag": null,
+            "packaging_flag": null,
+            "payment_adjustment_flag": null,
+            "payment_adjustment_flag2": null,
+            "payment_method_flag": null,
+            "composite_adjustment_flag": null,
+            "hcpcs_apc": null,
+            "payment_apc": null,
+            "edit_detail": null
+        }
+    ],
+    "edit_error": null
+}