Add support for phone matches postal outputs

HISTORY.rst

@@ -6,6 +6,9 @@ History
 3.1.0
 ++++++++++++++++++
 
+* Added support for the ``/billing_phone/matches_postal`` and
+  ``/shipping_phone/matches_postal`` outputs. These are available as the
+  ``matches_postal`` attribute on ``minfraud.model.Phone``.
 * Added ``cryptomus`` to the ``/payment/processor`` validation.
 
 3.0.0 (2025-02-10)

minfraud/models.py

@@ -509,6 +509,14 @@ class Phone(_Serializable):
     ``False`` when the number is not VoIP. If the phone number was not
     provided or we do not have data for it, the property will be ``None``."""
 
+    matches_postal: Optional[bool]
+    """This is ```True``` if the phone number's prefix is commonly
+    associated with the postal code. It is ```False``` if the prefix is not
+    associated with the postal code. It is non-```None``` only when the phone
+    number is in the US, the number prefix is in our database, and the
+    postal code and country are provided in the request.
+    """
+
     network_operator: Optional[str]
     """The name of the original network operator associated with the phone
     number. This field does not reflect phone numbers that have been ported
@@ -524,13 +532,15 @@ def __init__(
         *,
         country: Optional[str] = None,
         is_voip: Optional[bool] = None,
+        matches_postal: Optional[bool] = None,
         network_operator: Optional[str] = None,
         number_type: Optional[str] = None,
         **_,
     ) -> None:
         """Initialize a Phone instance."""
         self.country = country
         self.is_voip = is_voip
+        self.matches_postal = matches_postal
         self.network_operator = network_operator
         self.number_type = number_type
 

pyproject.toml

@@ -8,7 +8,7 @@ authors = [
 dependencies = [
     "aiohttp>=3.6.2,<4.0.0",
     "email_validator>=2.0.0,<3.0.0",
-    "geoip2>=5.0.1,<6.0.0",
+    "geoip2>=5.1.0,<6.0.0",
     "requests>=2.24.0,<3.0.0",
     "typing-extensions>=4.13.2",
     "voluptuous",

tests/data/factors-response.json

@@ -125,6 +125,7 @@
   "billing_phone": {
     "country": "US",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Verizon/1",
     "number_type": "fixed"
   },
@@ -168,6 +169,7 @@
   "shipping_phone": {
     "country": "CA",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Telus Mobility-SVR/2",
     "number_type": "mobile"
   },

tests/data/insights-response.json

@@ -125,6 +125,7 @@
   "billing_phone": {
     "country": "US",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Verizon/1",
     "number_type": "fixed"
   },
@@ -168,6 +169,7 @@
   "shipping_phone": {
     "country": "CA",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Telus Mobility-SVR/2",
     "number_type": "mobile"
   },

tests/test_models.py

@@ -234,12 +234,14 @@ def test_phone(self) -> None:
         phone = Phone(
             country="US",
             is_voip=True,
+            matches_postal=True,
             network_operator="Verizon/1",
             number_type="fixed",
         )
 
         self.assertEqual("US", phone.country)
         self.assertEqual(True, phone.is_voip)
+        self.assertEqual(True, phone.matches_postal)
         self.assertEqual("Verizon/1", phone.network_operator)
         self.assertEqual("fixed", phone.number_type)