{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ffraud-com/json-schema/ffraud-com-ip-response-schema.json",
  "title": "IpResponse",
  "description": "Flat structure for easy consumption. Optional fields are omitted when we have no data (no null soup).",
  "x-generated": "2026-11-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ffraud-com-openapi.json#/components/schemas/IpResponse",
  "type": "object",
  "required": [
    "success",
    "ip",
    "fraud_score",
    "risk",
    "proxy",
    "vpn",
    "tor",
    "relay",
    "hosting",
    "mobile",
    "is_abuser",
    "is_crawler",
    "recent_abuse",
    "connection_type",
    "is_residential_proxy",
    "shared_connection",
    "is_private",
    "confidence",
    "data_completeness"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "description": "Keyed calls only: the id of this request; quote it to support. A batch shares one. The public answer is cached and carries none."
    },
    "success": {
      "type": "boolean"
    },
    "ip": {
      "type": "string"
    },
    "fraud_score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "risk": {
      "type": "string",
      "enum": [
        "none",
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "reason": {
      "type": "string",
      "description": "Plain-English explanation of the score."
    },
    "proxy": {
      "type": "boolean"
    },
    "vpn": {
      "type": "boolean"
    },
    "tor": {
      "type": "boolean"
    },
    "relay": {
      "type": "boolean"
    },
    "hosting": {
      "type": "boolean"
    },
    "mobile": {
      "type": "boolean"
    },
    "is_abuser": {
      "type": "boolean"
    },
    "is_crawler": {
      "type": "boolean"
    },
    "recent_abuse": {
      "type": "boolean",
      "description": "Abuse confirmed within the last 30 days."
    },
    "connection_type": {
      "type": "string"
    },
    "proxy_type": {
      "type": "string",
      "description": "Raw IP2Proxy PX12 class: PUB, VPN, WEB, RES, DCH, SES."
    },
    "is_residential_proxy": {
      "type": "boolean"
    },
    "shared_connection": {
      "type": "boolean"
    },
    "ISP": {
      "type": "string"
    },
    "organization": {
      "type": "string"
    },
    "ASN": {
      "type": "integer"
    },
    "leased_through": {
      "type": "object",
      "description": "The IP leasing marketplace or IPv4 broker whose geofeed places this address block; the lessee sets that location, so geo keeps the estimate. Information only, not part of the score.",
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "leasing marketplace",
            "IPv4 broker"
          ]
        }
      }
    },
    "tunnel": {
      "type": "object",
      "description": "For a 6to4 or Teredo IPv6 address: the IPv4 address it carries. The verdict is that IPv4's own.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "6to4",
            "teredo"
          ]
        },
        "ipv4": {
          "type": "string"
        }
      }
    },
    "asn_registered": {
      "type": "string",
      "format": "date",
      "description": "When the network (ASN) got its current registration at its regional registry; a number passed to a new holder shows that date. Context only, not part of the score."
    },
    "vpn_provider": {
      "type": "string"
    },
    "cloud_provider": {
      "type": "string"
    },
    "relay_service": {
      "type": "string"
    },
    "threat_type": {
      "type": "string",
      "description": "PX12 threat class: SPAM, SCANNER, BOTNET."
    },
    "threat_tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "is_private": {
      "type": "boolean"
    },
    "subnet_abuse_ratio": {
      "type": "number",
      "format": "float",
      "description": "Fraction of the /24 flagged abusive (0.0-1.0)."
    },
    "subnet_total_ips": {
      "type": "integer"
    },
    "subnet_abuser_count": {
      "type": "integer"
    },
    "confidence": {
      "type": "string",
      "enum": [
        "high",
        "medium",
        "low"
      ]
    },
    "data_completeness": {
      "type": "number",
      "format": "float",
      "description": "Fraction of data layers that returned data (0.0-1.0)."
    },
    "rdns_classification": {
      "type": "string",
      "enum": [
        "residential",
        "mobile",
        "hosting",
        "vpn",
        "corporate",
        "education",
        "government",
        "no_ptr",
        "unknown"
      ]
    },
    "hostname": {
      "type": "string",
      "description": "Reverse-DNS (PTR) hostname, when published."
    },
    "isp_domain": {
      "type": "string",
      "description": "Domain of the ISP / network operator."
    },
    "first_seen": {
      "type": "string",
      "format": "date-time",
      "description": "When this IP was first observed."
    },
    "last_seen": {
      "type": "string",
      "format": "date-time",
      "description": "When this IP's intelligence was last confirmed."
    },
    "times_seen": {
      "type": "integer",
      "description": "Times observed across our cycles."
    },
    "total_reports": {
      "type": "integer",
      "description": "Aggregate community + honeypot reports for this IP."
    },
    "distinct_reporters": {
      "type": "integer",
      "description": "Distinct independent reporters."
    },
    "open_ports": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Open ports observed by our own scan sensors."
    },
    "vulnerabilities": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Known CVE identifiers for services observed on this IP."
    },
    "whois": {
      "$ref": "#/$defs/Whois"
    },
    "residential_proxy": {
      "$ref": "#/$defs/ResidentialProxy"
    },
    "carrier": {
      "$ref": "#/$defs/Carrier"
    },
    "company": {
      "$ref": "#/$defs/Company"
    },
    "geo": {
      "$ref": "#/$defs/Geo"
    }
  },
  "$defs": {
    "Carrier": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "mcc": {
          "type": "string"
        },
        "mnc": {
          "type": "string"
        }
      }
    },
    "Company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "domain": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "isp",
            "hosting",
            "business",
            "education",
            "government"
          ]
        },
        "network": {
          "type": "string",
          "description": "CIDR / range string for the company's network block."
        },
        "country": {
          "type": "string"
        }
      }
    },
    "Geo": {
      "type": "object",
      "properties": {
        "country": {
          "type": "string"
        },
        "country_name": {
          "type": "string"
        },
        "region": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "latitude": {
          "type": "number",
          "format": "float"
        },
        "longitude": {
          "type": "number",
          "format": "float"
        },
        "timezone": {
          "type": "string"
        },
        "asn": {
          "type": "string"
        },
        "asn_org": {
          "type": "string"
        },
        "isp": {
          "type": "string"
        }
      }
    },
    "ResidentialProxy": {
      "type": "object",
      "properties": {
        "detected": {
          "type": "boolean"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "very_high",
            "high",
            "medium",
            "low"
          ]
        },
        "recency": {
          "type": "string",
          "enum": [
            "active",
            "recent",
            "aging",
            "stale"
          ]
        },
        "last_seen": {
          "type": "string",
          "format": "date-time"
        },
        "first_seen": {
          "type": "string",
          "format": "date-time"
        },
        "persistence_days": {
          "type": "integer"
        },
        "times_seen": {
          "type": "integer"
        },
        "multi_provider": {
          "type": "boolean"
        },
        "provider_count": {
          "type": "integer"
        }
      }
    },
    "Whois": {
      "type": "object",
      "properties": {
        "network": {
          "type": "string"
        },
        "netname": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "org_name": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "abuse_contact": {
          "type": "string"
        },
        "source": {
          "type": "string"
        }
      }
    }
  }
}