openapi: 3.0.1 info: title: IPQualityScore API description: >- Real-time fraud prevention and threat intelligence API from IPQualityScore (IPQS). Covers proxy/VPN/Tor and IP reputation scoring, email and phone validation, malicious URL scanning, device fingerprinting, transaction risk scoring, and dark-web leaked-data checks. The API key is passed as a path parameter and responses are returned as JSON. termsOfService: https://www.ipqualityscore.com/terms-of-service contact: name: IPQualityScore Support url: https://www.ipqualityscore.com/contact version: '1.0' servers: - url: https://www.ipqualityscore.com/api/json paths: /ip/{api_key}/{ip}: get: operationId: proxyDetection tags: - IP Reputation summary: Proxy, VPN, Tor, and IP reputation lookup. description: >- Scores an IP address for proxy, VPN, and Tor usage, bot status, recent abuse, and abuse velocity, returning a 0-100 fraud score plus geolocation and connection metadata. Adding optional billing, shipping, payment, and order parameters enables Transaction Scoring, returning an additional transaction_details object. parameters: - name: api_key in: path required: true description: Your IPQualityScore API key. schema: type: string - name: ip in: path required: true description: The IPv4 or IPv6 address to look up. schema: type: string - name: strictness in: query required: false description: Adjusts lookup depth and sensitivity (0-3). 1 is recommended. schema: type: integer minimum: 0 maximum: 3 - name: user_agent in: query required: false description: User's browser user agent for improved accuracy. schema: type: string - name: user_language in: query required: false description: User's preferred language (e.g., en-US). schema: type: string - name: allow_public_access_points in: query required: false description: Bypass checks for public access points such as universities. schema: type: boolean - name: order_amount in: query required: false description: Transaction Scoring - the order amount for the transaction. schema: type: number - name: billing_email in: query required: false description: Transaction Scoring - billing email address. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ProxyDetectionResponse' /email/{api_key}/{email}: get: operationId: emailValidation tags: - Email Validation summary: Validate an email address. description: >- Verifies an email address for validity, deliverability, disposable or temporary domains, spam traps, honeypots, and recent abuse, returning a fraud score and DNS/MX checks. parameters: - name: api_key in: path required: true description: Your IPQualityScore API key. schema: type: string - name: email in: path required: true description: The URL-encoded email address to validate. schema: type: string - name: timeout in: query required: false description: Seconds to wait for a mailbox provider response (1-60, default 7). schema: type: integer minimum: 1 maximum: 60 - name: fast in: query required: false description: Prioritize speed over deep verification. schema: type: boolean - name: abuse_strictness in: query required: false description: Adjusts abuse-pattern detection (0-2). schema: type: integer minimum: 0 maximum: 2 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EmailValidationResponse' /phone/{api_key}/{phone}: get: operationId: phoneValidation tags: - Phone Validation summary: Validate a phone number. description: >- Validates a phone number across 150+ countries, returning carrier, line type, active status, geolocation, and a fraud score. parameters: - name: api_key in: path required: true description: Your IPQualityScore API key. schema: type: string - name: phone in: path required: true description: The phone number to validate. schema: type: string - name: country in: query required: false description: Comma-separated country codes to prefer for verification (e.g., US,CA). schema: type: string - name: strictness in: query required: false description: Adjusts verification requirements (0-2). schema: type: integer minimum: 0 maximum: 2 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PhoneValidationResponse' /url/{api_key}/{url}: get: operationId: maliciousUrlScanner tags: - URL Scanner summary: Scan a URL or domain for threats. description: >- Scans a URL or domain for phishing, malware, parking, spam, and suspicious content, returning a risk score, domain reputation, and a content category. parameters: - name: api_key in: path required: true description: Your IPQualityScore API key. schema: type: string - name: url in: path required: true description: The URL-encoded URL or domain to scan. schema: type: string - name: strictness in: query required: false description: Adjusts sensitivity (0-2). 0 is least strict and recommended. schema: type: integer minimum: 0 maximum: 2 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UrlScannerResponse' /fingerprint/{api_key}: post: operationId: deviceFingerprint tags: - Device Fingerprint summary: Score a device fingerprint. description: >- Analyzes 300+ data points about a user's device and session to detect bots, emulators, and high-risk behavior, returning a fraud score and device signals. parameters: - name: api_key in: path required: true description: Your IPQualityScore API key. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FingerprintRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FingerprintResponse' /leaked/{type}/{api_key}: get: operationId: leakedData tags: - Leaked Data summary: Check data against breached and dark-web databases. description: >- Checks an email, phone, username, password, or combination against breached and dark-web databases, returning exposure status, breach sources, and first-seen timestamps. parameters: - name: type in: path required: true description: Lookup type. schema: type: string enum: - email - password - username - emailpass - userpass - name: api_key in: path required: true description: Your IPQualityScore API key. schema: type: string - name: value in: query required: false description: >- The value to check. Passwords should be submitted as a POST parameter or header rather than in the URL for security. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LeakedDataResponse' components: securitySchemes: ApiKeyPath: type: apiKey in: path name: api_key description: IPQualityScore API key passed as a path parameter on each request. schemas: ProxyDetectionResponse: type: object properties: success: type: boolean message: type: string fraud_score: type: integer country_code: type: string region: type: string city: type: string ISP: type: string ASN: type: integer organization: type: string latitude: type: number longitude: type: number is_crawler: type: boolean connection_type: type: string proxy: type: boolean vpn: type: boolean tor: type: boolean active_vpn: type: boolean active_tor: type: boolean recent_abuse: type: boolean bot_status: type: boolean abuse_velocity: type: string mobile: type: boolean request_id: type: string transaction_details: $ref: '#/components/schemas/TransactionDetails' TransactionDetails: type: object properties: risk_score: type: integer risk_factors: type: array items: type: string valid_billing_address: type: boolean valid_shipping_address: type: boolean valid_billing_email: type: boolean valid_shipping_email: type: boolean valid_billing_phone: type: boolean fraudulent_behavior: type: boolean risky_username: type: boolean is_prepaid_card: type: boolean EmailValidationResponse: type: object properties: success: type: boolean message: type: string valid: type: boolean disposable: type: boolean smtp_score: type: integer overall_score: type: integer first_name: type: string generic: type: boolean common: type: boolean dns_valid: type: boolean honeypot: type: boolean deliverability: type: string frequent_complainer: type: boolean spam_trap_score: type: string catch_all: type: boolean timed_out: type: boolean suspect: type: boolean recent_abuse: type: boolean fraud_score: type: integer suggested_domain: type: string leaked: type: boolean domain_age: type: object first_seen: type: object sanitized_email: type: string request_id: type: string PhoneValidationResponse: type: object properties: success: type: boolean message: type: string valid: type: boolean active: type: boolean formatted: type: string local_format: type: string fraud_score: type: integer recent_abuse: type: boolean VOIP: type: boolean prepaid: type: boolean risky: type: boolean name: type: string carrier: type: string line_type: type: string country: type: string region: type: string city: type: string zip_code: type: string dialing_code: type: integer active_status: type: string leaked: type: boolean do_not_call: type: boolean request_id: type: string UrlScannerResponse: type: object properties: success: type: boolean message: type: string unsafe: type: boolean domain: type: string ip_address: type: string server: type: string content_type: type: string status_code: type: integer page_size: type: integer domain_rank: type: integer dns_valid: type: boolean parking: type: boolean spamming: type: boolean malware: type: boolean phishing: type: boolean suspicious: type: boolean adult: type: boolean risk_score: type: integer country_code: type: string category: type: string domain_age: type: object request_id: type: string FingerprintRequest: type: object properties: ip: type: string description: The user's IP address. request_id: type: string description: Device fingerprint request identifier from the client SDK. device_id: type: string user_agent: type: string transaction_details: type: object FingerprintResponse: type: object properties: success: type: boolean message: type: string fraud_chance: type: integer device_id: type: string bot_status: type: boolean is_crawler: type: boolean recent_abuse: type: boolean fraud_score: type: integer connection_type: type: string operating_system: type: string browser: type: string device_brand: type: string device_model: type: string request_id: type: string LeakedDataResponse: type: object properties: success: type: boolean message: type: string exposed: type: boolean plain_text_password: type: boolean source: type: array items: type: string first_seen: type: object request_id: type: string security: - ApiKeyPath: []